@swiftbrowser/web 0.5.6 → 0.6.0

package/src/layoutDom.ts

@@ -34,11 +34,15 @@
  */
 
 import type { LayoutEnvironment, LayoutNode, LayoutResult, Rect, ResolvedFont, TextLayout } from './layout';
+import { listRowBackgroundOf } from './layout';
+import { styleToCSS } from './styles';
+import type { ShapeStyle } from './protocol';
 import { applyChartChrome } from './chartDom';
 import { bitmapLaidOut } from './bitmaps';
 import { drawRichText } from './richText';
 import { bindScrollUnderBar, largeTitleOf, largeTitleScrolls } from './largeTitle';
 import { bindScrollEdgeBottom } from './scrollEdge';
+import { BOTTOM_GLASS_KIND, TOOLBAR_ANIMATION, TOOLBAR_TRANSITION, baseTiming, timingFor, transitionStart } from './animation';
 
 export interface LayoutDomContext {
   root: HTMLElement;
@@ -113,7 +117,7 @@ export function applyLayout(ctx: LayoutDomContext, result: LayoutResult): BoxCha
     // A former menu item that is laid out again (moved out of the menu), or a
     // `viewthatfits` candidate chosen again, shows again.
     if (el.hidden) el.hidden = false;
-    applyChrome(result, node, el, box, frame, scrollBottomInset(ctx, result, node, frame));
+    applyChrome(result, node, el, box, frame, scrollBottomInset(ctx, result, node, frame), previous === null, changes);
     if (node.kind === 'tab') setTabHidden(el, result.hidden.has(id));
   }
 
@@ -260,22 +264,79 @@ function placeEditControl(node: HTMLElement | null, rect: Rect | undefined, orig
 
 /**
  * iOS 26: the glass a screen's bottom toolbar items float on, one element
- * per capsule (engine `bottomGlass0` …), under the items (styles.css).
+ * per capsule (engine `bottomGlass0` …), under the items (styles.css). A
+ * capsule is known by the bottom toolbars drawn on it (`data-sb-toolbars`:
+ * the ids of those whose frames lie in it), not by its index, so a group
+ * that goes takes its own capsule with it and the groups after it keep
+ * theirs. A capsule that moves or resizes is reported in `changes` (kind
+ * `bottomglass`, no id) so the Animator tweens it with the toolbar's items;
+ * one that appears on a screen already there, or goes, scales and fades as
+ * the items do (`TOOLBAR_TRANSITION`), in the toolbar's own spring.
  */
-function syncBottomGlass(screen: HTMLElement, chrome: Record<string, Rect> | undefined, frame: Rect): void {
-  const existing = Array.from(screen.querySelectorAll<HTMLElement>(':scope > .sb-bottom-glass'));
-  let count = 0;
-  for (let rect = chrome?.['bottomGlass0']; rect; rect = chrome?.[`bottomGlass${count}`]) {
-    let glass = existing[count];
-    if (!glass) {
+function syncBottomGlass(
+  result: LayoutResult,
+  node: LayoutNode,
+  screen: HTMLElement,
+  chrome: Record<string, Rect> | undefined,
+  frame: Rect,
+  screenIsNew: boolean,
+  changes: BoxChange[],
+): void {
+  const unmatched = new Set(screen.querySelectorAll<HTMLElement>(':scope > .sb-bottom-glass:not([data-sb-exiting])'));
+  const toolbars = node.children.filter((child) => child.kind === 'toolbar' && child.props['placement'] === 'bottom');
+  for (let count = 0, rect = chrome?.['bottomGlass0']; rect; rect = chrome?.[`bottomGlass${++count}`]) {
+    const capsule = rect;
+    const ids = toolbars.filter((toolbar) => centeredIn(result.frames.get(toolbar.id), capsule)).map((toolbar) => String(toolbar.id));
+    const relative = { x: rect.x - frame.x, y: rect.y - frame.y, width: rect.width, height: rect.height };
+    let glass = Array.from(unmatched).find((candidate) => (candidate.dataset['sbToolbars'] ?? '').split(' ').some((id) => ids.includes(id)));
+    if (glass) {
+      unmatched.delete(glass);
+      const from = glassBox(glass);
+      if (!sameRect(from, relative)) changes.push({ id: -1, el: glass, kind: BOTTOM_GLASS_KIND, from, to: relative });
+    } else {
       glass = document.createElement('div');
       glass.className = 'sb-bottom-glass';
       screen.append(glass);
+      if (!screenIsNew) transitionGlass(glass, false);
+      changes.push({ id: -1, el: glass, kind: BOTTOM_GLASS_KIND, from: null, to: relative });
     }
+    glass.dataset['sbToolbars'] = ids.join(' ');
     placeChrome(glass, rect, frame);
-    count += 1;
   }
-  for (const extra of existing.slice(count)) extra.remove();
+  for (const extra of unmatched) transitionGlass(extra, true);
+}
+
+/** Whether `rect`'s center lies in `area` (a toolbar's frame spans its items, all on one capsule). */
+function centeredIn(rect: Rect | undefined, area: Rect): boolean {
+  if (!rect) return false;
+  const cx = rect.x + rect.width / 2;
+  const cy = rect.y + rect.height / 2;
+  return cx >= area.x && cx <= area.x + area.width && cy >= area.y && cy <= area.y + area.height;
+}
+
+/** The box a glass capsule was placed at (`placeChrome`), relative to its screen. */
+function glassBox(glass: HTMLElement): Rect {
+  const s = glass.style;
+  return { x: parseFloat(s.left) || 0, y: parseFloat(s.top) || 0, width: parseFloat(s.width) || 0, height: parseFloat(s.height) || 0 };
+}
+
+/** Scales and fades a bottom bar capsule in, or out (then removes it), as its toolbar's items do. */
+function transitionGlass(glass: HTMLElement, exit: boolean): void {
+  const timing = baseTiming(timingFor(TOOLBAR_ANIMATION));
+  const gone = transitionStart(TOOLBAR_TRANSITION, exit);
+  const frames: Keyframe[] = [
+    { opacity: gone.opacity ?? 0, transform: gone.transform ?? 'none' },
+    { opacity: 1, transform: 'none' },
+  ];
+  if (!exit) {
+    glass.animate(frames, { ...timing, fill: 'backwards' });
+    return;
+  }
+  glass.toggleAttribute('data-sb-exiting', true);
+  const out = glass.animate(frames.slice().reverse(), { ...timing, fill: 'forwards' });
+  const done = (): void => glass.remove();
+  out.finished.then(done, done);
+  window.setTimeout(done, timing.duration + timing.delay + 100);
 }
 
 function placeChrome(node: HTMLElement | null, rect: Rect | undefined, origin: Rect): void {
@@ -434,12 +495,23 @@ function applyChrome(
   box: Rect,
   frame: Rect,
   bottomInset: number,
+  isNew: boolean,
+  changes: BoxChange[],
 ): void {
   const chrome = result.chrome.get(node.id);
   // `.listRowSeparator(.hidden)`: a list row leaves out the separator below
   // it, or above it (the previous row's line; styles.css).
   setFlag(el, 'sbSeparatorBottom', chrome?.['separatorBottomHidden'] ? 'hidden' : null);
   setFlag(el, 'sbSeparatorTop', chrome?.['separatorTopHidden'] ? 'hidden' : null);
+  // `.listRowBackground(_:)`: the row's cell paint (styles.css reads it, and
+  // a card with such a row leaves its own background to its rows).
+  const rowBackground = chrome?.['row'] ? listRowBackgroundOf(node) : undefined;
+  const rowPaint = rowBackground !== undefined ? styleToCSS(rowBackground as ShapeStyle, 'paint').value : '';
+  if (el.style.getPropertyValue('--sb-row-background') !== rowPaint) {
+    if (rowPaint) el.style.setProperty('--sb-row-background', rowPaint);
+    else el.style.removeProperty('--sb-row-background');
+  }
+  setFlag(el, 'sbRowBackground', rowPaint ? '' : null);
   // iOS 26: the separator under a list row starts at its first text (styles.css).
   const separator = chrome?.['separator'];
   const leading = separator ? `${separator.x}px` : '';
@@ -598,10 +670,20 @@ function applyChrome(
       if (content && size) {
         const s = content.style;
         const axes = String(node.props['axes'] ?? 'vertical');
-        s.width = `${size.width}px`;
+        // `.scrollClipDisabled()`: the frame reaches past the viewport the
+        // scroll view laid out in (chrome `viewport`), by `before` and
+        // `after`. The content keeps its place (its margin is `before`) and
+        // runs `after` further, so it scrolls as far as it did and snaps
+        // against the viewport's edges.
+        const viewport = chrome?.['viewport'];
+        const before = viewport ? viewport.x - frame.x : 0;
+        const after = viewport ? frame.x + frame.width - (viewport.x + viewport.width) : 0;
+        s.width = `${size.width + after}px`;
         s.height = `${size.height + (axes === 'horizontal' ? 0 : bottomInset)}px`;
         s.marginLeft = `${rect ? rect.x - frame.x : 0}px`;
         s.marginTop = `${rect ? rect.y - frame.y : 0}px`;
+        el.style.scrollPaddingLeft = before ? `${before}px` : '';
+        el.style.scrollPaddingRight = after ? `${after}px` : '';
       }
       bindScrollUnderBar(el, frame, chrome?.['topInset'], chrome?.['largeTitle']);
       bindScrollEdgeBottom(el, String(node.props['axes'] ?? 'vertical') === 'horizontal' ? undefined : chrome?.['bottomInset']);
@@ -623,7 +705,9 @@ function applyChrome(
         bar.style.paddingTop = `${top}px`;
         bar.style.paddingBottom = `${bottom}px`;
       }
-      syncBottomGlass(el, chrome, frame);
+      syncBottomGlass(result, node, el, chrome, frame, isNew, changes);
+      // iOS 26 in a tab view: the search field under the title (styles.css).
+      setFlag(el, 'sbSearchTop', chrome?.['searchTop'] ? '' : null);
       const largeRect = chrome?.['largeTitle'];
       if (largeTitle) {
         if (largeRect) {

package/src/main.ts

@@ -47,12 +47,14 @@ const buildStatus = $<HTMLElement>('#build-status');
 
 const params = new URLSearchParams(location.search);
 const useMock = params.get('mock') === '1';
-const requestedApp = (params.get('app') ?? 'Counter').replace(/[^A-Za-z0-9_-]/g, '') || 'Counter';
+// The app: `?app=`, else the site's default (`define`, node/config.ts).
+const requestedApp = (params.get('app') ?? __SB_DEFAULT_APP__).replace(/[^A-Za-z0-9_-]/g, '') || __SB_DEFAULT_APP__;
 
 // Frame mode (the fake iPhone bezel, desktop and tests) or device mode (a
-// real phone: full screen, real safe areas, OS status bar). See deviceMode.ts;
-// the inline script in app/index.html pre-set the attribute with the same rule.
-const pageMode: PageMode = decidePageMode();
+// real phone: full screen, real safe areas, OS status bar; every screen of a
+// site built for a deployment). See deviceMode.ts; the inline script in
+// app/index.html pre-set the attribute with the same rule.
+const pageMode: PageMode = decidePageMode(location.search, window, __SB_PAGE_MODE__);
 applyPageMode(pageMode);
 const deviceMode = pageMode === 'device';
 

package/src/press.ts

@@ -0,0 +1,130 @@
+/**
+ * iOS 26's press feedback on Liquid Glass: while a finger is on a bar button
+ * or a glass button, the glass under it swells (scales up a little) and
+ * brightens; when the finger lifts it springs back. The stylesheet draws it
+ * (`[data-sb-pressed]`, `[data-sb-pressed-item]` in styles.css); this
+ * controller marks the glass under the pressed control from the pointer
+ * down to the pointer up, as UIKit highlights a button while it tracks a
+ * touch: lifting the highlight when the pointer leaves the control (plus a
+ * margin) and restoring it when it comes back.
+ *
+ * The glass under a control: a bar item's shared capsule (a `leading` or
+ * `trailing` toolbar), a bottom bar item's `.sb-bottom-glass` (the one
+ * under it: the glass is beside the toolbar, not around it), the back and
+ * More circles, the sidebar toggle, a `.glass` button, or the `.glassEffect`
+ * box around a button. A control on no glass (a plain or bordered button)
+ * keeps the stylesheet's `:active` dimming.
+ */
+
+/** The controls a press can highlight the glass under. */
+const PRESSABLE = '.sb-button, .sb-menu, .sb-navbar-back, .sb-navbar-more, .sb-navsplit-toggle, .sb-picker[data-sb-style="menu"]';
+
+/** Controls that are their own glass. */
+const OWN_GLASS = '.sb-navbar-back, .sb-navbar-more, .sb-navsplit-toggle, .sb-button[data-sb-style="glass"]';
+
+/** UIKit keeps a button highlighted while the touch stays within this far outside it. */
+export const PRESS_SLOP = 24;
+
+interface Press {
+  pointerId: number;
+  control: HTMLElement;
+  surface: HTMLElement;
+  /** Where the control was on the pointer down (its bounds plus the slop hold the press). */
+  bounds: DOMRect;
+  held: boolean;
+}
+
+export class PressEffects {
+  private press: Press | null = null;
+
+  constructor(private readonly root: HTMLElement) {
+    root.addEventListener('pointerdown', this.onPointerDown, true);
+  }
+
+  dispose(): void {
+    this.root.removeEventListener('pointerdown', this.onPointerDown, true);
+    this.release();
+  }
+
+  private readonly onPointerDown = (event: PointerEvent): void => {
+    if (this.press || !event.isPrimary || (event.pointerType === 'mouse' && event.button !== 0)) return;
+    const control = (event.target as Element | null)?.closest<HTMLElement>(PRESSABLE);
+    if (!control || !this.root.contains(control) || isDisabled(control)) return;
+    const surface = glassSurfaceOf(control, this.root);
+    if (!surface) return;
+    this.press = { pointerId: event.pointerId, control, surface, bounds: control.getBoundingClientRect(), held: false };
+    this.hold(true);
+    window.addEventListener('pointermove', this.onPointerMove);
+    window.addEventListener('pointerup', this.onPointerUp);
+    window.addEventListener('pointercancel', this.onPointerUp);
+  };
+
+  private readonly onPointerMove = (event: PointerEvent): void => {
+    const press = this.press;
+    if (!press || event.pointerId !== press.pointerId) return;
+    const b = press.bounds;
+    const inside =
+      event.clientX >= b.left - PRESS_SLOP &&
+      event.clientX <= b.right + PRESS_SLOP &&
+      event.clientY >= b.top - PRESS_SLOP &&
+      event.clientY <= b.bottom + PRESS_SLOP;
+    this.hold(inside);
+  };
+
+  private readonly onPointerUp = (event: PointerEvent): void => {
+    if (this.press && event.pointerId === this.press.pointerId) this.release();
+  };
+
+  /** Marks (or unmarks) the pressed glass and the control on it. */
+  private hold(held: boolean): void {
+    const press = this.press;
+    if (!press || press.held === held) return;
+    press.held = held;
+    press.surface.toggleAttribute('data-sb-pressed', held);
+    if (press.control !== press.surface) press.control.toggleAttribute('data-sb-pressed-item', held);
+  }
+
+  private release(): void {
+    this.hold(false);
+    this.press = null;
+    window.removeEventListener('pointermove', this.onPointerMove);
+    window.removeEventListener('pointerup', this.onPointerUp);
+    window.removeEventListener('pointercancel', this.onPointerUp);
+  }
+}
+
+/** A control the renderer disabled (`.disabled(true)` marks the element around it). */
+function isDisabled(control: HTMLElement): boolean {
+  return control.closest('[data-sb-disabled]') !== null || control.getAttribute('aria-disabled') === 'true';
+}
+
+/**
+ * The Liquid Glass under `control`, or null when it sits on none (see the
+ * top of the file).
+ */
+export function glassSurfaceOf(control: HTMLElement, root: HTMLElement): HTMLElement | null {
+  if (control.matches(OWN_GLASS)) return control;
+  const toolbar = control.closest<HTMLElement>('.sb-toolbar');
+  if (toolbar && root.contains(toolbar)) {
+    const placement = toolbar.dataset['sbPlacement'];
+    if (placement === 'leading' || placement === 'trailing') return toolbar;
+    if (placement === 'bottom') return bottomGlassUnder(control, toolbar);
+    return null;
+  }
+  const glass = control.closest<HTMLElement>('[data-sb-glass]');
+  return glass && root.contains(glass) ? glass : null;
+}
+
+/** The bottom bar capsule a bottom toolbar item is drawn on: the screen's `.sb-bottom-glass` under its center. */
+function bottomGlassUnder(control: HTMLElement, toolbar: HTMLElement): HTMLElement | null {
+  const screen = toolbar.closest<HTMLElement>('.sb-navscreen');
+  if (!screen) return null;
+  const rect = control.getBoundingClientRect();
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+  for (const glass of screen.querySelectorAll<HTMLElement>(':scope > .sb-bottom-glass')) {
+    const g = glass.getBoundingClientRect();
+    if (cx >= g.left && cx <= g.right && cy >= g.top && cy <= g.bottom) return glass;
+  }
+  return null;
+}

package/src/protocol.ts

@@ -22,6 +22,8 @@ export interface RGBAColor {
 
 export type SemanticColorName =
   | 'primary'
+  /** `.foreground` (ForegroundStyle): the color where it is drawn (CSS `currentColor`). */
+  | 'foreground'
   | 'secondary'
   | 'accent'
   | 'systemBackground'
@@ -396,6 +398,12 @@ export interface Style {
    * 11 vertical) for the list row this styled element is.
    */
   listRowInsets?: EdgeInsets;
+  /**
+   * `.listRowBackground(_:)` with a `Color` (or ShapeStyle): the list row this
+   * styled element is (or is in) has its cell painted with it instead of the
+   * card's; `clear` shows the list's background.
+   */
+  listRowBackground?: ShapeStyle;
   /**
    * `.imageScale(_:)`: symbol images in the subtree (`image` with
    * `systemName`, and catalog `symbol` images) measure 0.8 / 1 / 1.25 of the
@@ -700,6 +708,8 @@ export interface TabProps {
   badge?: string;
   /** iOS 18 `Tab(role: .search)` (absent otherwise); Swift already put it last. */
   role?: 'search';
+  /** A catalog image (a custom symbol) for the bar item when there is no `systemImage` (absent otherwise). */
+  image?: string;
 }
 export type PickerStyle = 'segmented' | 'menu' | 'inline';
 /**
@@ -728,6 +738,14 @@ export interface GeometryProps {
    * only, as before.
    */
   reportsFrame?: boolean;
+  /**
+   * The Swift view the size is reported to. Swift keeps the element when
+   * another view takes the reader's place, and changes this: the next layout
+   * pass then reports the size again, unchanged or not, since the new view
+   * has not heard it. Also on every other element that reports its size
+   * (`reportsSize`).
+   */
+  reader?: number;
 }
 
 // Phase 6 kinds (docs/phase6/layout-containers.md).
@@ -842,6 +860,8 @@ export type DecorationRole = 'overlay' | 'background';
 export interface DecoratedProps {
   role: DecorationRole;
   alignment: FrameAlignment;
+  /** The decoration is in an `if`: aligned by its edges, its `.alignmentGuide`s unused (absent otherwise). */
+  conditional?: boolean;
 }
 // Phase 6 kinds (docs/phase6/chrome.md).
 
@@ -1814,6 +1834,12 @@ export interface ScrollViewProps {
   refreshing?: boolean;
   /** Phase 12 `.scrollTargetBehavior`: CSS scroll snapping on the axis. */
   snap?: 'viewAligned' | 'paging';
+  /**
+   * `.scrollClipDisabled()`: a horizontal scroll view's frame reaches the
+   * screen's sides (chrome `viewport` is its own rect), so its content draws
+   * past it while scrolling and snapping as before.
+   */
+  clipDisabled?: boolean;
 }
 
 export interface Style {

package/src/renderer.ts

@@ -35,6 +35,7 @@
 
 import {
   Animator,
+  barToolbarOf,
   EXIT_CLONE_CLASS,
   emptyPass,
   setTransition,
@@ -58,6 +59,7 @@ import { applyLayout, setTabHidden, type BoxChange } from './layoutDom';
 import { ghostClone } from './ghost';
 import { ExternalDrops } from './dragDrop';
 import { InteractionController, type InteractionHost } from './interaction';
+import { PressEffects } from './press';
 import { symbolOf, textOf, unwrapStyledNode } from './nodeQueries';
 import {
   INTERACTION_KINDS,
@@ -371,6 +373,7 @@ export class Renderer {
    * swipe back, the sheet drag, pull to refresh) and arbitrates between them.
    */
   readonly interaction: InteractionController;
+  private readonly pressEffects: PressEffects;
   /** Text, links and files dragged in from outside the page (src/dragDrop.ts). */
   private readonly externalDrops: ExternalDrops;
   /** `video` elements' media events, as `video` events (src/video.ts). */
@@ -820,6 +823,8 @@ export class Renderer {
       closeMenu: () => this.closeMenu(),
     };
     this.interaction = new InteractionController(host);
+    // iOS 26: the glass under a pressed bar button swells and springs back (src/press.ts).
+    this.pressEffects = new PressEffects(root);
     this.externalDrops = new ExternalDrops(host);
     root.addEventListener('change', this.onChange);
     root.addEventListener('pointerdown', this.onSliderPointerDown);
@@ -1430,6 +1435,7 @@ export class Renderer {
     this.root.removeEventListener('focusout', this.onFocusChange);
     this.root.removeEventListener('scroll', this.onScrollDismissKeyboard, true);
     this.interaction.dispose();
+    this.pressEffects.dispose();
     this.externalDrops.dispose();
     this.videoEvents.dispose();
     this.resizeObserver?.disconnect();
@@ -1573,7 +1579,14 @@ export class Renderer {
       }
     }
     if (node) {
-      node.props = asRecord(props);
+      const next = asRecord(props);
+      // Another Swift view now reads this element's size (a `geometry`
+      // element kept for a new page's reader): it knows no size yet, so the
+      // next layout pass reports the size even when it is unchanged.
+      if ((kind === 'geometry' || next['reportsSize'] === true) && next['reader'] !== node.props['reader']) {
+        this.reportedGeometry.delete(id);
+      }
+      node.props = next;
       // Phase 9: the next layout re-measures this subtree and its ancestors;
       // a screen's title also feeds the next screen's back label.
       if (node.kind === 'navscreen') {
@@ -1619,10 +1632,10 @@ export class Renderer {
       if (stack) refreshNavStack(stack);
     }
     if (kind === 'sheet' && el.parentElement) refreshSheets(el.parentElement);
-    if (kind === 'tabview') refreshTabBar(el);
+    if (kind === 'tabview') refreshTabBar(el, this.assets);
     if (kind === 'tab') {
       const tabview = tabViewOf(el);
-      if (tabview) refreshTabBar(tabview);
+      if (tabview) refreshTabBar(tabview, this.assets);
     }
     // The popover shows what its control had when it opened; drop it when
     // the control (or, for a `menu`, anything inside it) changes.
@@ -1697,9 +1710,9 @@ export class Renderer {
     // Phase 8: an alert fades in (and scales from 1.1) on its own.
     if (el.classList.contains('sb-alert') && !wasAttached) animateAlertIn(el);
     if (el.classList.contains('sb-tab')) {
-      if (parent.classList.contains('sb-tabview')) refreshTabBar(parent);
+      if (parent.classList.contains('sb-tabview')) refreshTabBar(parent, this.assets);
       const oldTabView = previousParent && previousParent !== container ? tabViewOf(previousParent) : null;
-      if (oldTabView && oldTabView !== parent) refreshTabBar(oldTabView);
+      if (oldTabView && oldTabView !== parent) refreshTabBar(oldTabView, this.assets);
     }
   }
 
@@ -1734,7 +1747,9 @@ export class Renderer {
       for (let a = parent; a && a !== this.root; a = a.parentElement!) ancestors.push(a);
       let rect: DOMRect | null = null;
       const matched: { id: string; el: HTMLElement; rect: DOMRect }[] = [];
-      if (this.passAnimates !== false) {
+      // A bar toolbar's items (and the toolbar) leave with a transition of
+      // their own in any pass (src/animation.ts, `implicitToolbars`).
+      if (this.passAnimates !== false || barToolbarOf(el, parent)) {
         this.passRootRect ??= this.animator.rootRect();
         rect = this.animator.rectOf(el, this.passRootRect);
         // `.matchedGeometryEffect`: where the matched boxes in the subtree were.
@@ -1766,7 +1781,7 @@ export class Renderer {
     }
     if (stack) refreshNavStack(stack);
     if (isSheet && parent) refreshSheets(parent);
-    if (tabview) refreshTabBar(tabview);
+    if (tabview) refreshTabBar(tabview, this.assets);
   }
 
   /** Forget an element in every map; detaches its node from the tree. */
@@ -2528,7 +2543,7 @@ function clampIndex(value: unknown, count: number): number {
  * the selected tab: only it is visible and interactive. The layout engine
  * confirms the hidden set at `commit`; this keeps the DOM right in between.
  */
-function refreshTabBar(tabview: HTMLElement): void {
+function refreshTabBar(tabview: HTMLElement, assets: AssetCatalog): void {
   const bar = tabview.querySelector<HTMLElement>(':scope > .sb-tabbar');
   if (!bar) return;
   const tabs = Array.from(slotOf(tabview).children).filter((c) => c.classList.contains('sb-tab')) as HTMLElement[];
@@ -2552,14 +2567,17 @@ function refreshTabBar(tabview: HTMLElement): void {
     item.setAttribute('aria-label', title);
     item.toggleAttribute('data-sb-selected', isSelected);
     const icon = item.querySelector<HTMLElement>(':scope > .sb-tabbar-icon');
-    if (icon && icon.dataset['sbSymbol'] !== symbol) {
+    const asset = symbol ? '' : (tab.dataset['sbAsset'] ?? '');
+    if (icon && (icon.dataset['sbSymbol'] !== symbol || (icon.dataset['sbAsset'] ?? '') !== asset)) {
       icon.dataset['sbSymbol'] = symbol;
+      if (asset) icon.dataset['sbAsset'] = asset;
+      else delete icon.dataset['sbAsset'];
       // iOS draws tab bar symbols in their filled form.
-      const svg = symbol ? renderSymbol(filledSymbolName(symbol)) : null;
-      if (svg) icon.replaceChildren(svg);
+      const glyph = symbol ? renderSymbol(filledSymbolName(symbol)) : asset ? tabAssetIcon(asset, assets) : null;
+      if (glyph) icon.replaceChildren(glyph);
       else icon.replaceChildren();
-      icon.toggleAttribute('data-sb-missing', Boolean(symbol) && !svg);
-      icon.hidden = !symbol;
+      icon.toggleAttribute('data-sb-missing', Boolean(symbol || asset) && !glyph);
+      icon.hidden = !symbol && !asset;
     }
     const label = item.querySelector<HTMLElement>(':scope > .sb-tabbar-title');
     if (label && label.textContent !== title) label.textContent = title;
@@ -2575,6 +2593,29 @@ function refreshTabBar(tabview: HTMLElement): void {
   });
 }
 
+/**
+ * A tab bar item's catalog icon: a custom symbol masks the item's color, in
+ * its `.fill` variant when the catalog has one (as iOS draws SF Symbols in a
+ * tab bar); any other image shows as it is. Null when the catalog has neither.
+ */
+function tabAssetIcon(name: string, assets: AssetCatalog): Element | null {
+  const asset = assets.images[`${name}.fill`]?.kind === 'symbol' ? assets.images[`${name}.fill`] : assets.images[name];
+  if (!asset) return null;
+  if (asset.kind === 'symbol') {
+    const mask = document.createElement('span');
+    mask.className = 'sb-tabbar-mask';
+    const url = `url("${asset.src}")`;
+    mask.style.setProperty('mask-image', url);
+    mask.style.setProperty('-webkit-mask-image', url);
+    return mask;
+  }
+  const img = document.createElement('img');
+  img.src = asset.src;
+  img.alt = '';
+  img.draggable = false;
+  return img;
+}
+
 // ---------------------------------------------------------------------------
 // Sheets
 // ---------------------------------------------------------------------------
@@ -2867,9 +2908,11 @@ function applyKindProps(el: HTMLElement, kind: ElementKind, props: ElementProps,
       break;
     }
     case 'tab': {
-      const { title, systemImage, badge, role } = props as TabProps;
+      const { title, systemImage, badge, role, image } = props as TabProps;
       el.dataset['sbTitle'] = title ?? '';
       el.dataset['sbSymbol'] = systemImage ?? '';
+      if (image) el.dataset['sbAsset'] = image;
+      else delete el.dataset['sbAsset'];
       if (badge) el.dataset['sbBadge'] = badge;
       else delete el.dataset['sbBadge'];
       if (role) el.dataset['sbRole'] = role;