@swiftbrowser/web 0.19.0 → 0.21.0

package/src/hostRequests.ts

@@ -202,6 +202,12 @@ export interface HostRequestEnvironment {
   languageModel?: LanguageModelHost;
   /** The app's files (files.ts: its IndexedDB home on a page, its sandbox natively); `FileManager` in @swiftbrowser/react calls it. */
   files?: FilesHost;
+  /**
+   * A dropped file the host left on disk (a `DropItem` with `url` and `size`,
+   * natively) as a `File` read on demand; a page never needs it, its drops
+   * carry the `File` itself.
+   */
+  fileFromReference?: (item: { type: string; name?: string; path?: string; url: string; size?: number }) => File;
   /** The browser's built-in translator (`translate`, translation.ts), where it has one. */
   translation?: TranslationHost;
   /** The browser's color chooser (`pickColor`, colorPicker.ts); it must open before it returns. */
@@ -210,18 +216,49 @@ export interface HostRequestEnvironment {
   undoManager?: UndoHost;
 }
 
+/**
+ * The type that, among a chooser's `accept`, asks for a folder rather than files (SwiftUI's `UTType.folder`).
+ * The chooser then answers with the files in the folder, at any depth, that the rest of `accept` allows.
+ */
+export const FOLDER_TYPE = 'public.folder';
+
+/**
+ * A chosen folder's files, as a `pickFiles` request answers them: those the
+ * rest of `accept` allows (an extension, a MIME type or a `type/*` pattern;
+ * any when it names none), each named by its path from the folder, the
+ * folder's own name first (`Bank/Leads/Saw.fxp`).
+ */
+export function folderFiles(files: File[], accept: string[]): File[] {
+  const allowed = accept.filter((part) => part !== FOLDER_TYPE).map((part) => part.toLowerCase());
+  const allows = (file: File): boolean =>
+    allowed.length === 0 ||
+    allowed.some((part) =>
+      part.startsWith('.') ? file.name.toLowerCase().endsWith(part)
+      : part.endsWith('/*') ? file.type.toLowerCase().startsWith(part.slice(0, -1))
+      : file.type.toLowerCase() === part);
+  return files.filter(allows).map((file) => {
+    const path = file.webkitRelativePath;
+    return path && path !== file.name ? new File([file], path, { type: file.type, lastModified: file.lastModified }) : file;
+  });
+}
+
 /**
  * The browser's file chooser: a hidden `<input type="file">` clicked at once,
  * inside the tap that sent the request (the loader performs the request while
  * the tap's click handler is still running; see wasm.ts). Resolves on
  * `change` with the files, or on `cancel` (the viewer closed the chooser)
  * with none. A browser without the `cancel` event never answers a dismissal;
- * the app's selection then just stays as it was.
+ * the app's selection then just stays as it was. With `FOLDER_TYPE` in
+ * `accept`, it is the folder chooser, answered as `folderFiles` says.
  */
 function chooseFiles(options: { accept: string; multiple: boolean }): Promise<File[]> {
+  const accept = options.accept.split(',').map((part) => part.trim()).filter((part) => part !== '');
+  const folder = accept.includes(FOLDER_TYPE);
   const input = document.createElement('input');
   input.type = 'file';
-  if (options.accept) input.accept = options.accept;
+  // A folder: the browser's folder chooser, which takes no `accept`; its files are filtered after.
+  if (folder) input.webkitdirectory = true;
+  else if (options.accept) input.accept = options.accept;
   input.multiple = options.multiple;
   // In the document (some browsers only open a chooser for an attached
   // input), but invisible and out of the way.
@@ -233,7 +270,10 @@ function chooseFiles(options: { accept: string; multiple: boolean }): Promise<Fi
       input.remove();
       resolve(files);
     };
-    input.addEventListener('change', () => finish(Array.from(input.files ?? [])), { once: true });
+    input.addEventListener('change', () => {
+      const files = Array.from(input.files ?? []);
+      finish(folder ? folderFiles(files, accept) : files);
+    }, { once: true });
     input.addEventListener('cancel', () => finish([]), { once: true });
   });
   input.click();

package/src/interaction.ts

@@ -102,6 +102,8 @@ export interface InteractionHost {
   readonly root: HTMLElement;
   send(event: RendererEvent): void;
   nodeOf(id: ElementId): LayoutNode | undefined;
+  /** How a dropped file reaches the app (src/dragDrop.ts `DragDropHost`). */
+  fileDrops?(): 'bytes' | 'reference';
   /** Open the popover of a `contextmenu` element anchored to it. */
   openContextMenu(anchor: HTMLElement, id: ElementId): void;
   /** A covered screen is about to show (a back swipe starts): lay it out if it is stale. */
@@ -318,7 +320,10 @@ export class InteractionController {
   // -------------------------------------------------------------------------
 
   private readonly onPointerDown = (event: PointerEvent): void => {
-    if (this.session || !event.isPrimary || (event.pointerType === 'mouse' && event.button !== 0)) return;
+    // One pointer at a time, but not only the primary one: a finger on a
+    // knob while another holds a key (a `touches` element, src/touches.ts,
+    // owns that one) drags, as in SwiftUI.
+    if (this.session || (event.pointerType === 'mouse' && event.button !== 0)) return;
     const target = event.target as HTMLElement | null;
     if (!target) return;
     // Pointer downs in a text field select text, never gesture; a slider

package/src/layout/engine.ts

@@ -1819,6 +1819,7 @@ export class LayoutPass {
         return this.pickerPlan(node, ctx, p).size;
       case 'host':
         return this.measureHost(node, p);
+      case 'registered':
       case 'geometry':
         // GeometryReader: the proposal, 10 on unconstrained axes.
         return { width: p.width ?? SHAPE_DEFAULT, height: p.height ?? SHAPE_DEFAULT };
@@ -3102,6 +3103,7 @@ export class LayoutPass {
       case 'canvas':
       case 'video':
       case 'host':
+      case 'registered':
         return;
       case 'vstack':
       case 'disclosuregroup':

package/src/main.ts

@@ -2,6 +2,7 @@
 import { easingFor, springEasing, timingFor } from './animation';
 import type { BuildEndPayload, BuildErrorPayload, BuildStartPayload } from './devEvents';
 import { ChromeColor } from './chromeColor';
+import { installDeviceFrame } from './deviceFrame';
 import { applyPageMode, decidePageMode, installViewportReadout, readViewportInsets, watchKeyboard, watchViewport, type PageMode } from './deviceMode';
 import { EMPTY_CATALOG, catalogPath, isAssetCatalog, type AssetCatalog } from './assets';
 import { createMockApp } from './mock';
@@ -228,7 +229,8 @@ typeSizeSelect.addEventListener('change', () => {
 
 /**
  * Phase 7: the horizontal size class Swift sees (`regular` from 700 CSS px of
- * screen width). The frame is always compact; device mode follows the viewport.
+ * screen width). The iPhone frame is compact, the iPad frame regular, and
+ * without a frame (or in device mode) it follows the window.
  */
 function currentSizeClass(): HorizontalSizeClass {
   return horizontalSizeClassFor(screen.clientWidth);
@@ -260,6 +262,15 @@ if (deviceMode) {
   // `?debug=viewport` shows the numbers the measurement reads, over the app.
   const readout = new URLSearchParams(location.search).get('debug') === 'viewport' ? installViewportReadout() : undefined;
   watchKeyboard((height) => renderer.setKeyboard(height), { root: device, onRead: readout });
+} else if (!document.documentElement.hasAttribute('data-sb-embed')) {
+  // A desktop preview: the toolbar's Device picker (deviceFrame.ts) draws the
+  // app in an iPhone, an iPad or no device; the renderer re-reads the
+  // screen's size when it changes, and Swift hears a new size class.
+  const sizeClassMayHaveChanged = (): void => {
+    if (sentSizeClass !== null && currentSizeClass() !== sentSizeClass) sendEnvironment();
+  };
+  installDeviceFrame(renderer, { onChange: sizeClassMayHaveChanged });
+  watchViewport(sizeClassMayHaveChanged);
 }
 
 // ---------------------------------------------------------------------------

package/src/page.css

@@ -141,6 +141,43 @@ body {
   border-color: transparent;
 }
 
+.toolbar-close {
+  flex: 0 0 auto;
+  display: grid;
+  place-items: center;
+  width: 28px;
+  height: 28px;
+  margin-right: -4px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: transparent;
+  color: var(--page-fg);
+  cursor: pointer;
+}
+
+.toolbar-close svg circle {
+  fill: currentColor;
+  opacity: 0.12;
+}
+
+.toolbar-close svg path {
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.8;
+  stroke-linecap: round;
+  opacity: 0.7;
+}
+
+.toolbar-close:hover svg circle {
+  opacity: 0.2;
+}
+
+/* ?toolbar=0 (the toolbar's close button, src/deviceFrame.ts): the app alone. */
+html[data-sb-toolbar="hidden"] .toolbar {
+  display: none;
+}
+
 .toolbar-select {
   font: inherit;
   padding: 5px 8px;
@@ -172,6 +209,34 @@ body {
   word-break: break-word;
 }
 
+/* No device (html[data-sb-frame="none"], src/deviceFrame.ts): the page is
+   the toolbar over the app, which fills the rest of the window and lays out
+   for its size as the window is resized. */
+html[data-sb-frame="none"]:not([data-sb-mode="device"]) body {
+  display: flex;
+  flex-direction: column;
+  height: 100dvh;
+  min-height: 0;
+  overflow: hidden;
+}
+
+html[data-sb-frame="none"]:not([data-sb-mode="device"]) .stage {
+  flex: 1 1 auto;
+  min-height: 0;
+  align-items: stretch;
+  padding: 0;
+  gap: 0;
+}
+
+html[data-sb-frame="none"]:not([data-sb-mode="device"]) .status {
+  position: fixed;
+  left: 16px;
+  right: 16px;
+  bottom: 16px;
+  z-index: 10;
+  max-width: none;
+}
+
 /* ---------------------------------------------------------------------------
    Device mode (html[data-sb-mode="device"], see src/deviceMode.ts): no
    toolbar, no stage padding, the page behind the app in the OS appearance's

package/src/pinnedViews.ts

@@ -10,6 +10,12 @@
  * scroll event each header is moved by a transform along the axis. The
  * laid-out positions are left alone (offsets, not client rects), so the
  * transform never feeds back into where the header is reckoned to be.
+ *
+ * Where the browser has scroll-driven animations, a header is instead moved
+ * by one (styles.css `sb-pinned`) along its scroll view's timeline, from the
+ * scroll offset where it starts to pin to the one where its section's end
+ * stops it. The browser then moves it in step with the scroll itself, where a
+ * scroll event, a frame late on iOS, would leave it jittering.
  */
 
 import type { PinnedView } from './protocol';
@@ -43,6 +49,9 @@ export function pinnedFooterOffset(viewEnd: number, footer: Span, sectionStart:
 
 const registered = new Map<HTMLElement, Set<PinnedView>>();
 
+/** Whether headers pin by a scroll-driven animation (styles.css), not by script on each scroll event. */
+const scrollDriven = typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('animation-timeline', '--sb-pin-y');
+
 /** Called by the renderer for every stack and grid: registers, updates or forgets its pinned views. */
 export function setPinnedViews(el: HTMLElement, pinned: PinnedView[] | undefined): void {
   const views = new Set<PinnedView>(Array.isArray(pinned) ? pinned.filter((view) => view === 'sectionHeaders' || view === 'sectionFooters') : []);
@@ -55,6 +64,7 @@ export function setPinnedViews(el: HTMLElement, pinned: PinnedView[] | undefined
           if (view) {
             view.style.transform = '';
             view.style.zIndex = '';
+            unpin(view);
           }
         }
       }
@@ -98,7 +108,8 @@ function draw(stack: HTMLElement, views: Set<PinnedView>): void {
       if (header) {
         const at = layoutOrigin(header, scroller);
         const span: Span = { start: horizontal ? (at?.x ?? sectionStart) : (at?.y ?? sectionStart), length: horizontal ? header.offsetWidth : header.offsetHeight };
-        move(header, horizontal, pinnedHeaderOffset(viewStart, span, sectionEnd));
+        if (scrollDriven) pin(header, horizontal, span.start - (horizontal ? 0 : topInset(scroller)), pinnedHeaderOffset(Infinity, span, sectionEnd));
+        else move(header, horizontal, pinnedHeaderOffset(viewStart, span, sectionEnd));
       }
     }
     if (views.has('sectionFooters')) {
@@ -119,6 +130,32 @@ function move(view: HTMLElement, horizontal: boolean, offset: number): void {
   view.style.zIndex = '1';
 }
 
+/**
+ * Pins a header by a scroll-driven animation: from the scroll offset `from`, where its view's start reaches it, it
+ * moves with the scroll for `room` and stays there. The scroll view names its timelines (styles.css).
+ */
+function pin(view: HTMLElement, horizontal: boolean, from: number, room: number): void {
+  view.style.transform = '';
+  view.style.zIndex = '1';
+  if (room <= 0) {
+    unpin(view);
+    return;
+  }
+  const start = Math.round(from * 100) / 100;
+  const end = Math.round((from + room) * 100) / 100;
+  view.style.animation = 'sb-pinned linear both';
+  view.style.setProperty('animation-timeline', horizontal ? '--sb-pin-x' : '--sb-pin-y');
+  view.style.setProperty('animation-range', `${start}px ${end}px`);
+  view.style.setProperty('--sb-pinned-to', horizontal ? `${room}px 0` : `0 ${room}px`);
+}
+
+function unpin(view: HTMLElement): void {
+  view.style.animation = '';
+  view.style.removeProperty('animation-timeline');
+  view.style.removeProperty('animation-range');
+  view.style.removeProperty('--sb-pinned-to');
+}
+
 /** Moves every pinned view to its place: after a layout, and on every scroll event. */
 export function drawPinnedViews(): void {
   for (const [stack, views] of registered) {

package/src/protocol.ts

@@ -378,6 +378,11 @@ export interface Style {
   /** Unit point the scale grows from (default 0.5/0.5). */
   scaleAnchor?: UnitPoint;
   shadow?: Shadow;
+  /**
+   * `.compositingGroup()`: the box is drawn as one layer before the effects around it apply, so a `shadow` (here or
+   * on a box around it) is cast by the box as a whole rather than by each view it draws.
+   */
+  compositingGroup?: boolean;
   /** `.clipped()`: `overflow: hidden` on the box. */
   clipped?: boolean;
 
@@ -1062,6 +1067,19 @@ export interface ElementPropsByKind {
   searchfield: SearchFieldProps;
   tapgesture: TapGestureProps;
   host: HostProps;
+  registered: RegisteredProps;
+}
+
+/**
+ * A view a package registered under `name` with `ViewRegistry`: on a page
+ * its own DOM (src/viewRegistry.ts), in a native app a SwiftUI view. It
+ * takes the proposal, 10 on an unconstrained axis, as `GeometryReader`
+ * does; its children, if any, are the native view's to place.
+ */
+export interface RegisteredProps {
+  name: string;
+  /** JSON, as the app wrote it, for the view. */
+  props: Record<string, unknown>;
 }
 
 export type ElementKind = keyof ElementPropsByKind;
@@ -1552,7 +1570,17 @@ export type RendererEvent =
   | ScrollGeometryEvent
   | AnimationCompleteEvent
   // The page's undo and redo keys, for the app's undo manager (src/undo.ts)
-  | UndoEvent;
+  | UndoEvent
+  // A registered view's own answer (src/viewRegistry.ts)
+  | RegisteredEvent;
+
+/** What a registered view sent (`context.send(value)`), for the element's `onEvent`. */
+export interface RegisteredEvent {
+  type: 'registered';
+  id: ElementId;
+  name: string;
+  value: unknown;
+}
 
 /**
  * Phase 13: the page's answer to the `request` op with this `id`: `value`
@@ -2251,7 +2279,19 @@ export interface DropItem {
   type: string;
   text?: string;
   name?: string;
+  /** A file's bytes as base64 (a Swift app's destination; `file` for a React one). */
   data?: string;
+  /**
+   * The file as the browser holds it, by reference (a React host asks for
+   * `reference` drops, src/dragDrop.ts): never serialized, so a dropped
+   * folder of large files costs no memory until a file is read.
+   */
+  file?: File;
+  /** The file's path inside a dropped folder, the folder's name first (`Photos/2025/a.jpg`); absent for a file dropped on its own. */
+  path?: string;
+  /** Natively: a dropped file still on disk, its `file:` URL and size, read on demand through the files bridge. */
+  url?: string;
+  size?: number;
 }
 /**
  * A drag over a `dropdestination`: it `entered`, `exited`, or `performed`

package/src/renderer.ts

@@ -126,6 +126,7 @@ import {
   type TabProps,
   type TabViewProps,
   type HostProps,
+  type RegisteredProps,
   type TextFieldProps,
   type TextProps,
   type TextRun,
@@ -171,8 +172,9 @@ import { TouchPaging } from './touchPaging';
 import { isScrollVisible } from './scrollVisibility';
 import { applyDefaultScrollAnchor, keepScrollAnchors } from './scrollAnchor';
 import { EMPTY_CATALOG, assetColorVar, type AssetCatalog } from './assets';
-import { HIERARCHY_OPACITY, colorToCSS, effectsCSS, styleToCSS, type PaintCSS } from './styles';
+import { HIERARCHY_OPACITY, colorToCSS, effectsCSS, shadowCSS, styleToCSS, type PaintCSS } from './styles';
 import { hostContent, onHostContentChange } from './hostContent';
+import { type RegisteredViewInstance, ViewRegistry } from './viewRegistry';
 import { HoverTracker, applyPointerAndEffects, safeAreaOverlap } from './pointerEffects';
 import { colorMultiplyFilter } from './colorMultiply';
 import { largeTitleOf, largeTitleTextOf } from './largeTitle';
@@ -193,6 +195,14 @@ export class RendererError extends Error {
 }
 
 const KIND_ATTR = 'sbKind';
+/**
+ * The kinds that draw what they show themselves: a shadow of a box around one falls on it as a whole (castShadows,
+ * styles.css), where a container hands it on to the views inside.
+ */
+const DRAWN_KINDS: ReadonlySet<string> = new Set([
+  'text', 'image', 'divider', 'color', 'shape', 'textfield', 'toggle', 'picker', 'gauge', 'searchfield', 'registered', 'chart',
+  'stepper', 'slider', 'datepicker', 'texteditor', 'video', 'canvas',
+]);
 const ID_ATTR = 'sbId';
 /** `animationToken` of a `styled` box, kept across `update` to detect changes. */
 const ANIMATION_TOKEN = 'sbAnimationToken';
@@ -252,6 +262,7 @@ export { SHEET_DISMISS_DRAG } from './interaction';
 
 const ALL_KINDS: ReadonlySet<string> = new Set<ElementKind>([
   'host',
+  'registered',
   'text',
   'vstack',
   'hstack',
@@ -422,6 +433,8 @@ export class Renderer {
   private readonly hostContents = new Map<ElementId, HTMLElement>();
   /** The `host` elements, adopted or still waiting for their content. */
   private readonly hosts = new Set<ElementId>();
+  /** The registered views (src/viewRegistry.ts) built for `registered` elements, by element: the name each was built for. */
+  private readonly registeredViews = new Map<ElementId, { name: string; instance: RegisteredViewInstance | undefined }>();
   private readonly hostSizes = new WeakMap<HTMLElement, { width: number; height: number }>();
   private readonly hostMeasures = new Map<string, { width: number; height: number }>();
   private readonly stopHostChanges: () => void;
@@ -440,6 +453,12 @@ export class Renderer {
   private readonly pressEffects: PressEffects;
   /** Text, links and files dragged in from outside the page (src/dragDrop.ts). */
   private readonly externalDrops: ExternalDrops;
+  /**
+   * How a dropped file reaches the app: base64 `data` in the event (a Swift
+   * app) or the `File` by reference (a React app in the same page sets
+   * `reference`; a dropped folder then comes as its files by path).
+   */
+  fileDrops: 'bytes' | 'reference' = 'bytes';
   private readonly pinches: PinchController;
   private readonly touches: TouchesController;
   private readonly touchPaging: TouchPaging;
@@ -1025,6 +1044,7 @@ export class Renderer {
       root,
       send: (event) => this.onEvent(event),
       nodeOf: (id) => this.nodes.get(id),
+      fileDrops: () => this.fileDrops,
       openContextMenu: (anchor, id) => this.openContextMenu(anchor, id),
       revealScreen: (screen) => this.revealScreen(screen),
       isMenuOpen: (id) => this.menu?.anchorId === id,
@@ -1258,6 +1278,7 @@ export class Renderer {
           this.syncFocus();
           // The focus the app moved shows or hides a screen's keyboard bar.
           if (this.focusedFieldId() !== focusedBefore && this.hasKeyboardToolbars()) this.layout();
+          this.castShadows();
           this.performScrolls(op.animation != null);
           this.performOffsetScrolls(op.animation != null);
           this.checkLazySpacers();
@@ -1275,6 +1296,55 @@ export class Renderer {
     }
   }
 
+  /**
+   * SwiftUI's `.shadow` on a container falls on each view it draws (its texts, shapes, images, controls and
+   * backgrounds), on their own shadows too, and not on the container as a whole unless a `.compositingGroup()` in
+   * between draws the views as one. Each box with a shadow (`data-sb-shadow`) hands its views the shadows to cast:
+   * its own, then those of the boxes around it, up to a compositing group (`--sb-shadow-filter`, which styles.css
+   * gives each drawn view's `filter`, and which a box that clips, masks or composites takes for itself). A box's own
+   * background, painted with its children inside, casts them as `box-shadow` instead.
+   */
+  private castShadows(): void {
+    const sources = this.root.querySelectorAll<HTMLElement>('[data-sb-shadow]');
+    const cast = new Set(this.root.querySelectorAll<HTMLElement>('[data-sb-shadow-cast]'));
+    if (sources.length === 0 && cast.size === 0) return;
+    const filters = new Map<HTMLElement, { filter: string; box: string }>();
+    // The shadows that reach the views inside `el` from the boxes around it, up to a compositing group or a drawn
+    // view, which takes those around it as one and hands none on.
+    const above = (el: HTMLElement): { filter: string; box: string } => {
+      for (let up = el.parentElement; up && up !== this.root; up = up.parentElement) {
+        if (up.dataset['sbComposite'] !== undefined || DRAWN_KINDS.has(up.dataset[KIND_ATTR] ?? '')) break;
+        const found = filters.get(up);
+        if (found) return found;
+      }
+      return { filter: '', box: '' };
+    };
+    // Document order: a box comes before the boxes inside it.
+    for (const el of sources) {
+      const outer = above(el);
+      const filter = `${el.dataset['sbShadow']} ${outer.filter}`.trim();
+      const box = [el.dataset['sbShadowBox'], outer.box].filter(Boolean).join(', ');
+      filters.set(el, { filter, box });
+      if (el.style.getPropertyValue('--sb-shadow-filter') !== filter) el.style.setProperty('--sb-shadow-filter', filter);
+    }
+    // A background painted on a box (its children inside) casts them as a box-shadow.
+    if (sources.length > 0) {
+      // A box that clips, masks or composites casts them for its background already, with what it holds.
+      for (const el of this.root.querySelectorAll<HTMLElement>('.sb-styled[data-sb-background]:not([data-sb-as-one])')) {
+        const { box } = filters.get(el) ?? above(el);
+        if (!box) continue;
+        if (el.style.boxShadow !== box) el.style.boxShadow = box;
+        el.dataset['sbShadowCast'] = '';
+        cast.delete(el);
+      }
+    }
+    // Those no shadow reaches any more.
+    for (const el of cast) {
+      el.style.boxShadow = '';
+      delete el.dataset['sbShadowCast'];
+    }
+  }
+
   /**
    * `withAnimation(_:completionCriteria:_:completion:)`: the pass's `commit`
    * carried a completion serial; once the animations its commit started have
@@ -2057,6 +2127,34 @@ export class Renderer {
       this.hosts.add(id);
       this.adoptHostContent(id, el, props as HostProps);
     }
+    if (kind === 'registered') this.adoptRegistered(id, el, props as RegisteredProps);
+  }
+
+  /**
+   * A `registered` element's view (src/viewRegistry.ts): built for its name,
+   * given the new props after; a name nothing registered shows itself, as an
+   * unknown kind does. The element's own children are the native view's: on
+   * a page the stylesheet hides them.
+   */
+  private adoptRegistered(id: ElementId, el: HTMLElement, props: RegisteredProps): void {
+    const values = asRecord(props.props);
+    const current = this.registeredViews.get(id);
+    if (current && current.name === props.name) {
+      current.instance?.update?.(values);
+      return;
+    }
+    current?.instance?.dispose?.();
+    const name = props.name;
+    const instance = ViewRegistry.make(name, { id, props: values, send: (value) => this.onEvent({ type: 'registered', id, name, value }) });
+    this.registeredViews.set(id, { name, instance });
+    let content = instance?.element;
+    if (!content) {
+      content = div('sb-registered-missing');
+      content.textContent = name;
+    }
+    content.classList.add('sb-registered-content');
+    el.querySelector(':scope > .sb-registered-content')?.remove();
+    el.prepend(content);
   }
 
   /** A toolbar whose placement changed to or from `largeTitle` moves between its screen's content slot and large title. */
@@ -2469,6 +2567,7 @@ export class Renderer {
     this.noteScroll(id, kind, props);
     this.noteVisibility(id, kind, props);
     if (kind === 'host') this.adoptHostContent(id, el, props as HostProps);
+    if (kind === 'registered') this.adoptRegistered(id, el, props as RegisteredProps);
     if (kind === 'toolbar') this.rehomeToolbar(id, el, op);
     const newToken = el.dataset[ANIMATION_TOKEN];
     const tokenChanged = (previous?.tokenChanged ?? false) || (newToken !== undefined && newToken !== oldToken);
@@ -2704,6 +2803,8 @@ export class Renderer {
       this.hostContents.delete(id);
     }
     this.hosts.delete(id);
+    this.registeredViews.get(id)?.instance?.dispose?.();
+    this.registeredViews.delete(id);
     this.elements.delete(id);
     this.boxes.delete(id);
     this.dirty.delete(id);
@@ -2979,6 +3080,9 @@ function createShell(kind: ElementKind): HTMLElement {
     case 'host':
       // The page's content element is adopted by the renderer (`adoptHostContent`).
       return div('sb-host');
+    case 'registered':
+      // Its view is built by the renderer (`adoptRegistered`).
+      return div('sb-registered');
     case 'button': {
       const el = document.createElement('button');
       el.type = 'button';
@@ -4136,6 +4240,9 @@ function applyKindProps(el: HTMLElement, kind: ElementKind, props: ElementProps,
     case 'lazyspacer':
       el.dataset['axis'] = (props as LazySpacerProps).axis === 'horizontal' ? 'horizontal' : 'vertical';
       break;
+    case 'registered':
+      // The renderer builds its view (`adoptRegistered`).
+      break;
     default: {
       const unknown: never = kind;
       throw new RendererError(`Unknown element kind ${String(unknown)}`);
@@ -4282,9 +4389,10 @@ function applyShape(el: HTMLElement, props: ShapeProps): void {
     s.border = `${width}px ${stroke.dash?.length ? 'dashed' : 'solid'} ${color}`;
     el.dataset['sbStroke'] = stroke.inset ? 'inset' : 'center';
   }
-  // A fill with a drop shadow (`.shadow(.drop(…))` on the style).
+  // A fill with a drop shadow (`.shadow(.drop(…))` on the style), then the shadows of the boxes around the shape
+  // (castShadows), which styles.css gives a shape without one of its own.
   const shadow = (props.fill as { shadow?: ShapeShadow } | null)?.shadow;
-  s.filter = shadow && typeof shadow === 'object' ? shapeShadowCSS(shadow) : '';
+  s.filter = shadow && typeof shadow === 'object' ? `${shapeShadowCSS(shadow)} var(--sb-shadow-filter, )` : '';
   const mask = shapeTrimMask(props.trim);
   if (mask) {
     s.setProperty('mask-image', mask);
@@ -4893,15 +5001,29 @@ export function applyStyle(el: HTMLElement, style: Style): void {
   }
 
   // Phase 6 visual effects: CSS only, the layout engine never sees them.
-  const effects = effectsCSS(style);
+  // A shadow is not the box's own filter: as SwiftUI's `.shadow` on a container, it falls on each view the box draws
+  // (castShadows). A box that clips, masks or composites what it holds draws it as one, so the shadows around it are
+  // cast by it too (`--sb-shadow-filter`, which castShadows sets).
+  const effects = effectsCSS(style, { shadow: false });
   if (effects.transform) s.transform = effects.transform;
   if (effects.transformOrigin) s.transformOrigin = effects.transformOrigin;
-  if (effects.filter) s.filter = effects.filter;
-  // `.colorMultiply`: an SVG filter, first so the other filters see its colors.
-  if (style.colorMultiply) {
-    const multiply = colorMultiplyFilter(style.colorMultiply, el);
-    s.filter = effects.filter ? `${multiply} ${effects.filter}` : multiply;
-  }
+  const multiply = style.colorMultiply ? colorMultiplyFilter(style.colorMultiply, el) : '';
+  const asOne = style.compositingGroup === true || style.cornerRadius != null || style.clipped === true || (style.mask != null && typeof style.mask === 'object');
+  const filter = [multiply, effects.filter ?? '', asOne ? 'var(--sb-shadow-filter, )' : ''].filter(Boolean).join(' ');
+  if (filter) s.filter = filter;
+  if (asOne) el.dataset['sbAsOne'] = '';
+  else delete el.dataset['sbAsOne'];
+  if (style.shadow) {
+    el.dataset['sbShadow'] = `drop-shadow(${shadowCSS(style.shadow)})`;
+    el.dataset['sbShadowBox'] = shadowCSS(style.shadow);
+  } else if (el.dataset['sbShadow'] !== undefined) {
+    delete el.dataset['sbShadow'];
+    delete el.dataset['sbShadowBox'];
+    s.removeProperty('--sb-shadow-filter');
+    s.removeProperty('--sb-shadow-box');
+  }
+  if (style.compositingGroup) el.dataset['sbComposite'] = '';
+  else delete el.dataset['sbComposite'];
   // Phase 7: `.hidden()` keeps the box (the engine lays it out) but draws
   // nothing and takes no input; `.mask { }` clips the box to a style's alpha.
   if (effects.hidden) {

package/src/scrollTransition.ts

@@ -35,7 +35,8 @@ export function setScrollTransition(el: HTMLElement, style: Style): void {
     }
     return;
   }
-  const own = effectsCSS(style);
+  // Its shadow is cast by the views it draws (renderer.ts castShadows), not by it.
+  const own = effectsCSS(style, { shadow: false });
   registered.set(el, {
     spec,
     base: { transform: own.transform ?? '', filter: own.filter ?? '', opacity: style.opacity ?? 1 },