@swiftbrowser/web 0.1.0 → 0.2.0

package/src/protocol.ts

@@ -26,7 +26,44 @@ export type SemanticColorName =
   | 'accent'
   | 'systemBackground'
   | 'secondarySystemBackground'
-  | 'clear';
+  /** UIKit's semantic colors, by their iOS names (`Color(uiColor:)`). */
+  | 'tertiarySystemBackground'
+  | 'systemGroupedBackground'
+  | 'secondarySystemGroupedBackground'
+  | 'tertiarySystemGroupedBackground'
+  | 'label'
+  | 'secondaryLabel'
+  | 'tertiaryLabel'
+  | 'quaternaryLabel'
+  | 'placeholderText'
+  | 'separator'
+  | 'opaqueSeparator'
+  | 'systemFill'
+  | 'secondarySystemFill'
+  | 'tertiarySystemFill'
+  | 'quaternarySystemFill'
+  | 'systemGray2'
+  | 'systemGray3'
+  | 'systemGray4'
+  | 'systemGray5'
+  | 'systemGray6'
+  /** The system palette (`Color.red`, `UIColor.systemRed`…): `--sb-color-<name>`. */
+  | 'red'
+  | 'orange'
+  | 'yellow'
+  | 'green'
+  | 'mint'
+  | 'teal'
+  | 'cyan'
+  | 'blue'
+  | 'indigo'
+  | 'purple'
+  | 'pink'
+  | 'brown'
+  | 'gray'
+  | 'clear'
+  /** `TintShapeStyle` (`.tint` as a style): the nearest `.tint(_:)`, else the accent color. */
+  | 'tint';
 
 /**
  * Semantic color the renderer resolves for the current color scheme. `a`
@@ -275,6 +312,11 @@ export interface Style {
   background?: ShapeStyle;
   frame?: Frame;
   cornerRadius?: number;
+  /**
+   * `.background(_:)` in a container shape (`.containerShape`): the
+   * background's corner radius. Unlike `cornerRadius` it does not clip.
+   */
+  backgroundCornerRadius?: number;
   opacity?: number;
   /** Dims the subtree (`opacity: 0.4`) and blocks input (`pointer-events: none`). */
   disabled?: boolean;
@@ -293,6 +335,8 @@ export interface Style {
    */
   animation?: Animation;
   animationToken?: number;
+  /** This box is a `Label`'s icon: a list row tints it (its title keeps the row's color). */
+  labelIcon?: boolean;
   /** How this subtree appears and disappears inside an animated commit. */
   transition?: Transition;
   // Phase 5
@@ -364,6 +408,34 @@ export type HStackAlignment = 'top' | 'center' | 'bottom';
 
 export interface TextProps {
   text: string;
+  /**
+   * Rich text (`Text + Text`, `Text(AttributedString)`, an interpolated
+   * image, a Text-only modifier such as `.italic()`): the text as runs, each
+   * styled on its own. `text` is then the plain content.
+   */
+  runs?: TextRun[];
+}
+/**
+ * One run of a rich text: its `text`, or an inline `image` (an `image`
+ * element's props). Unset fields take the text's own style.
+ */
+export interface TextRun {
+  text?: string;
+  image?: ImageProps;
+  /** A Font JSON object applied over the text's font (as `styled` `font`). */
+  font?: Record<string, unknown>;
+  italic?: boolean;
+  /** A ShapeStyle JSON object (as `styled` `foreground`). */
+  foreground?: unknown;
+  /** A line through or under the run; `color` defaults to the run's own. */
+  strikethrough?: { color?: unknown };
+  underline?: { color?: unknown };
+  /** Extra space after each character, in points. */
+  kerning?: number;
+  /** Points to raise the run by (negative lowers it). */
+  baselineOffset?: number;
+  /** A tap on the run sends `link` with this URL. */
+  link?: string;
 }
 export interface VStackProps {
   spacing: number | null;
@@ -399,6 +471,12 @@ export interface StyledProps {
 /** Same alignment names as `Frame.alignment`; later children draw on top. */
 export interface ZStackProps {
   alignment: FrameAlignment;
+  /**
+   * Report the element's laid-out size with `geometry` events, as a
+   * `geometry` element does (an anchor preference's wrapper; see
+   * docs/ops-protocol.md, "Preferences").
+   */
+  reportsSize?: boolean;
 }
 /** `systemName` is an SF Symbol name; the renderer picks the closest glyph. */
 export interface SymbolImageProps {
@@ -415,7 +493,69 @@ export interface AssetImageProps {
   name: string;
   resizable: boolean;
 }
-export type ImageProps = SymbolImageProps | AssetImageProps;
+/**
+ * Phase 13: a remote image (`AsyncImage`). The page loaded it already (an
+ * `image` request op) and told the app its pixel size; `width` / `height`
+ * are that size in points, the intrinsic size the layout engine uses unless
+ * `resizable`.
+ */
+export interface UrlImageProps {
+  url: string;
+  resizable: boolean;
+  width: number;
+  height: number;
+}
+/**
+ * A `UIImage` / `CGImage` bitmap (`Image(uiImage:)`): a recipe the page draws
+ * (src/bitmaps.ts). `width` / `height` are the image's size in points, the
+ * intrinsic size unless `resizable`. See docs/ops-protocol.md, "Bitmaps and
+ * Core Image".
+ */
+export interface BitmapImageProps {
+  bitmap: BitmapRecipe;
+  resizable: boolean;
+  width: number;
+  height: number;
+  /** `.interpolation(.none)`: scaled without smoothing. */
+  interpolation?: 'none';
+}
+export type ImageProps = SymbolImageProps | AssetImageProps | UrlImageProps | BitmapImageProps;
+
+/**
+ * How to draw a bitmap: the `imagedata` source named by `source` (null: an
+ * empty image) with `steps` applied in order, in Core Image's coordinate
+ * space (units of source pixels, origin at the bottom left). The result is
+ * `width` × `height` pixels.
+ */
+export interface BitmapRecipe {
+  source: string | null;
+  /** A frame of an animated source (a GIF), composed as the frames before it leave the canvas; absent: the file as it is. */
+  frame?: number;
+  steps: BitmapStep[];
+  width: number;
+  height: number;
+}
+
+/** A point in Core Image's space. */
+export type BitmapPoint = [number, number];
+
+/** One step of a recipe; the formulas are in docs/ops-protocol.md. */
+export type BitmapStep =
+  | { op: 'crop' | 'render'; x: number; y: number; width: number; height: number }
+  | { op: 'clamp' }
+  | { op: 'sepiaTone'; intensity: number }
+  | { op: 'edges'; intensity: number }
+  | { op: 'crystallize'; radius: number; center: BitmapPoint }
+  | { op: 'pixellate'; scale: number; center: BitmapPoint }
+  | { op: 'gaussianBlur'; radius: number }
+  | { op: 'unsharpMask'; radius: number; intensity: number }
+  | { op: 'vignette'; intensity: number; radius: number; center: BitmapPoint; size: number }
+  /** Core Graphics drawing an image in a rectangle: every point p goes to (p.x × sx + tx, p.y × sy + ty). */
+  | { op: 'place'; sx: number; sy: number; tx: number; ty: number }
+  /** A clip to a rounded rectangle (an ellipse when the radii are half its sides). */
+  | { op: 'roundedClip'; x: number; y: number; width: number; height: number; rx: number; ry: number }
+  /** `UIImage.withTintColor`: every pixel the color (straight RGBA, 0…1), at the pixel's alpha times the color's. */
+  | { op: 'tint'; r: number; g: number; b: number; a: number };
 export type DividerProps = Record<string, never>;
 export type ScrollAxes = 'vertical' | 'horizontal' | 'both';
 export interface ScrollViewProps {
@@ -469,7 +609,9 @@ export interface ColorProps {
   color: Color;
 }
 /** Phase 6 adds `containerRelative` (`ContainerRelativeShape`): a rounded rectangle with `cornerRadius`. */
-export type ShapeKind = 'rectangle' | 'roundedRectangle' | 'circle' | 'capsule' | 'ellipse' | 'containerRelative';
+export type ShapeKind = 'rectangle' | 'roundedRectangle' | 'circle' | 'capsule' | 'ellipse' | 'containerRelative'
+  /** A custom shape drawn from its path (`ShapeProps.path`). */
+  | 'path';
 export interface Stroke {
   /** Phase 6: any ShapeStyle; a gradient stroke falls back to its first stop. */
   color: ShapeStyle;
@@ -480,6 +622,12 @@ export interface Stroke {
    * `data-sb-stroke`.
    */
   inset?: boolean;
+  /** A custom shape's `StrokeStyle` (a built-in shape's border has none of these). */
+  lineCap?: 'butt' | 'round' | 'square';
+  lineJoin?: 'miter' | 'round' | 'bevel';
+  miterLimit?: number;
+  dash?: number[];
+  dashPhase?: number;
 }
 /** `fill: null` means the current foreground color; fills its proposal. */
 export interface ShapeProps {
@@ -488,9 +636,33 @@ export interface ShapeProps {
   /** Phase 6: any ShapeStyle. */
   fill: ShapeStyle | null;
   stroke: Stroke | null;
+  /**
+   * `.trim(from:to:)`: the part of the outline between the fractions, drawn
+   * as a conic mask around the center from 3 o'clock, clockwise (exact for a
+   * circle). Absent when the shape is not trimmed.
+   */
+  trim?: { from: number; to: number };
+  /**
+   * A custom shape (`shape: "path"`, src/pathShape.ts): SVG path data for a
+   * rectangle of `size` at the origin, the size the element reported
+   * (`reportsSize`). Empty until the first report.
+   */
+  path?: string;
+  size?: { width: number; height: number };
+  /** `FillStyle(eoFill: true)`: overlapping parts of the path cancel out. */
+  fillRule?: 'evenodd';
+  /** The element reports its laid-out size (a custom shape draws its path for it). */
+  reportsSize?: boolean;
+  /**
+   * An animated change of the shape's `animatableData`: the path at each
+   * fraction of the change (`paths[index[i]]` at `progress[i]`), played in
+   * the commit's animation.
+   */
+  frames?: { progress: number[]; index: number[]; paths: string[] };
 }
 /** Phase 8: `full` is `.fullScreenCover` (the card fills the screen). */
-export type Detent = 'medium' | 'large' | 'full';
+/** `height:<points>` / `fraction:<f>`: `.presentationDetents([.height(300)])`, `.fraction(0.4)`. */
+export type Detent = 'medium' | 'large' | 'full' | `height:${number}` | `fraction:${number}`;
 /**
  * Always a root-level element (child of id 0) placed after the app's tree. A
  * `tap` with the sheet's own id is a dismiss request.
@@ -510,6 +682,10 @@ export interface TabViewProps {
 export interface TabProps {
   title: string;
   systemImage: string | null;
+  /** iOS 18 `Tab(…).badge(…)`: a red badge on the bar item (absent when none). */
+  badge?: string;
+  /** iOS 18 `Tab(role: .search)` (absent otherwise); Swift already put it last. */
+  role?: 'search';
 }
 export type PickerStyle = 'segmented' | 'menu' | 'inline';
 /**
@@ -615,7 +791,7 @@ export type GaugeStyle =
 /**
  * `Gauge`: `value` is normalized to 0...1. Children in order: the label (when
  * `hasLabel`) and the current value label (when `hasCurrentValueLabel`).
- * Circular styles render as linear for now.
+ * Circular styles draw a ring with one of the labels in the middle.
  */
 export interface GaugeProps {
   value: number;
@@ -641,7 +817,16 @@ export interface DecoratedProps {
  * a popover built from the current items (`button`/`navlink` rows that send
  * `tap`, `picker` sections that send `select`, `divider`, `section`, `text`).
  */
-export type MenuProps = Record<string, never>;
+/**
+ * Lazy menus: `deferred: true` while the items are not built (only the label
+ * is a child). The page sends a `menu` event with `open: true` when the
+ * viewer opens it and shows the popover once the items arrive (`deferred:
+ * false`), and `open: false` when it closes. Absent when the app builds the
+ * items eagerly (headless runs, the mocks).
+ */
+export interface MenuProps {
+  deferred?: boolean;
+}
 export type ToolbarPlacement = 'trailing' | 'leading' | 'principal' | 'bottom';
 /**
  * `.toolbar { ToolbarItem(placement:) { ... } }`, an extra child of a
@@ -662,8 +847,13 @@ export interface SearchFieldProps {
   /** Defaults to "Search". */
   placeholder: string;
 }
-/** `.onTapGesture`: one child, the child's size; a click anywhere on it sends `tap`. */
-export type TapGestureProps = Record<string, never>;
+/**
+ * `.onTapGesture`: one child, the child's size; a click anywhere on it sends
+ * `tap`. `location` (`onTapGesture { point in }`) adds the click's point.
+ */
+export interface TapGestureProps {
+  location?: boolean;
+}
 
 export interface ElementPropsByKind {
   text: TextProps;
@@ -758,7 +948,238 @@ export interface DefaultsOp {
   values: Record<string, unknown>;
 }
 
-export type Op = CreateOp | UpdateOp | InsertOp | RemoveOp | CommitOp | DefaultsOp;
+/**
+ * Phase 13: something only the page can do for the app. The loader performs
+ * it (src/hostRequests.ts) and answers with a `ResponseEvent` of the same
+ * `id`; the renderer never sees it.
+ */
+export interface RequestOp {
+  op: 'request';
+  id: number;
+  kind: 'fetch' | 'image' | 'share' | 'pickFiles' | 'notification' | 'scanner' | 'websocket' | 'openURL' | 'webAuth' | 'media' | 'download' | 'clipboard' | 'translate' | 'pickColor';
+  params:
+    | FetchRequestParams
+    | ImageRequestParams
+    | ShareRequestParams
+    | PickFilesRequestParams
+    | NotificationRequestParams
+    | ScannerRequestParams
+    | WebSocketRequestParams
+    | OpenURLRequestParams
+    | WebAuthRequestParams
+    | MediaRequestParams
+    | DownloadRequestParams
+    | ClipboardRequestParams
+    | TranslateRequestParams
+    | PickColorRequestParams;
+}
+/**
+ * `translate` (Translation; src/translation.ts): `availability` of a pair
+ * (`source` null: detected from `text`), or `translate` the `texts` from
+ * `source` (null: detected) to `target`, BCP 47 tags. `allowDownload`: the
+ * session may download the pair's model.
+ */
+export interface TranslateRequestParams {
+  action: 'availability' | 'translate';
+  source?: string | null;
+  target: string;
+  text?: string;
+  texts?: string[];
+  allowDownload?: boolean;
+}
+/** `pickColor` (`ColorPicker`; src/colorPicker.ts): the chooser opens at `color` (`#rrggbb`). */
+export interface PickColorRequestParams {
+  color?: string;
+}
+/**
+ * `URLSessionWebSocketTask`: one call on a socket (src/webSocket.ts). `open`
+ * takes `url` and `protocols`; the others the `socket` id `open` answered.
+ */
+/** `openURL` (`OpenURLAction`, a link in a `Text`, `UIApplication.open`): the page opens `url` in a new tab; the value is null. */
+/**
+ * `webAuth` (AuthenticationServices; docs/ops-protocol.md, "Signing in"):
+ * `start` opens `url`, the provider's authorize page, in a popup window and
+ * answers `{ url }`, the callback page URL the window ended at; `cancel` closes
+ * the window, and the pending `start` fails with `cancelled: …`.
+ * `callbackScheme` is the app's scheme the redirect stands for, `callbackPage`
+ * the callback page the app put in its place; `ephemeral` is the app's wish
+ * for a private session, which a popup cannot grant.
+ */
+export interface WebAuthRequestParams {
+  action?: 'start' | 'cancel';
+  url?: string;
+  callbackScheme?: string;
+  callbackPage?: string;
+  ephemeral?: boolean;
+}
+export interface OpenURLRequestParams {
+  url: string;
+}
+export interface WebSocketRequestParams {
+  action: 'open' | 'send' | 'receive' | 'close';
+  url?: string;
+  protocols?: string[];
+  socket?: number;
+  /** `send`: a text message. */
+  string?: string;
+  /** `send`: a binary message, base64. */
+  data?: string;
+  /** `close`: the close code and reason. */
+  code?: number;
+  reason?: string;
+}
+/** `URLSession`: one HTTP request. `body` is base64; `timeout` in ms (0: none). */
+export interface FetchRequestParams {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body: string | null;
+  timeout?: number;
+}
+/** `AsyncImage`: decode the image at `url` and report its pixel size. */
+export interface ImageRequestParams {
+  url: string;
+}
+
+/**
+ * `ShareLink`: share through the Web Share API, or download where the browser
+ * cannot. `images` are asset-catalog names, shared (or downloaded) as their
+ * files. The response value is a `ShareResult`.
+ */
+export interface ShareRequestParams {
+  title?: string;
+  text?: string;
+  url?: string;
+  images?: string[];
+  /** `Image(uiImage:)` items: recipes the page draws into PNG files. */
+  bitmaps?: BitmapRecipe[];
+  /** Files the app made: a `Transferable` item's exported bytes, a `UIImage`'s own file. */
+  files?: SharedFile[];
+}
+
+/** A file the app hands to the page whole: its name, MIME type and bytes (base64). */
+export interface SharedFile {
+  name: string;
+  type: string;
+  data: string;
+}
+
+/**
+ * Saving (Photos' change requests, `UIImageWriteToSavedPhotosAlbum`): the
+ * page downloads each file, catalog image and bitmap (a PNG named after
+ * `title`). The response value is a `ShareResult` (`downloaded`).
+ */
+export interface DownloadRequestParams {
+  title?: string;
+  files?: SharedFile[];
+  images?: string[];
+  bitmaps?: BitmapRecipe[];
+}
+
+/**
+ * `UIPasteboard.general`: `write` copies `text`, or the first picture (a
+ * file, catalog image or bitmap, as PNG) to the system clipboard and answers
+ * `{}`; `readText` answers `{ text }`.
+ */
+export interface ClipboardRequestParams {
+  action: 'write' | 'readText';
+  text?: string;
+  files?: SharedFile[];
+  images?: string[];
+  bitmaps?: BitmapRecipe[];
+}
+
+/**
+ * `PhotosPicker`: let the viewer choose files with the browser's file
+ * chooser. `accept` is the input's `accept` (`image/*,video/*`; empty: any
+ * file). The response value is a `PickFilesResult`; a dismissed chooser
+ * answers with no items.
+ */
+export interface PickFilesRequestParams {
+  accept: string;
+  multiple: boolean;
+}
+
+/**
+ * UserNotifications (docs/ops-protocol.md, "Notifications"): `status` reads
+ * `Notification.permission`, `request` asks for it, `show` presents a
+ * notification that came due (`title` absent: the badge only), `close`
+ * closes delivered ones by identifier, `badge` sets the app badge. The
+ * response value is a `NotificationResult`.
+ */
+export interface NotificationRequestParams {
+  action: 'status' | 'request' | 'show' | 'close' | 'badge';
+  /** `show`: the request's identifier, the notification's `tag`. */
+  id?: string;
+  title?: string;
+  subtitle?: string;
+  body?: string;
+  silent?: boolean;
+  /** `show` and `badge`: the app badge (0 clears it). */
+  badge?: number;
+  /** `close`: the identifiers to close. */
+  ids?: string[];
+}
+
+/**
+ * AVFoundation's capture sessions (docs/ops-protocol.md, "Code scanning"):
+ * `probe` asks whether the page can scan `formats` (`BarcodeDetector` names)
+ * with a camera; `scan` opens the camera over the page until a code is found
+ * or the viewer closes it, or, where the browser cannot read codes, asks the
+ * viewer to type one. The response value is a `ScannerResult`.
+ */
+export interface ScannerRequestParams {
+  action: 'probe' | 'scan';
+  formats: string[];
+  torch?: boolean;
+  vibrate?: boolean;
+  /** Which camera: the back one (`environment`, the default) or the front one (`user`). */
+  facing?: 'environment' | 'user';
+}
+
+/**
+ * Phase 18: one save of a SwiftData store (`ModelContext.save()`, or the main
+ * context's autosave at the end of an event). The loader hands it to the page,
+ * which writes it to the app's IndexedDB database (src/swiftData.ts) and
+ * passes every store back at the next launch as `SB_SWIFTDATA`. `clear`
+ * (`ModelContainer.deleteAllData()`) empties the store before `put`.
+ */
+export interface SwiftDataOp {
+  op: 'swiftdata';
+  store: string;
+  put: SwiftDataRecord[];
+  delete: number[];
+  clear?: boolean;
+}
+
+/** A saved model: its key in the store, its entity (class) name and its properties' JSON. */
+export interface SwiftDataRecord {
+  id: number;
+  entity: string;
+  values: Record<string, unknown>;
+}
+
+/**
+ * A bitmap's source, sent once (by content `key`) before the first element
+ * that draws it: an encoded image file (`mime`, `data`) or a pixel buffer
+ * (`format`, `pixels`: one gray or four RGBA bytes per pixel, rows from the
+ * top). The bytes are base64 in printed ops; from a module with the
+ * `sb_bytes_*` exports, src/wasm.ts reads them out of linear memory
+ * (docs/ops-protocol.md, "Bytes"). `width` × `height` is its size in pixels, as
+ * drawn (a JPEG's EXIF rotation applied). The renderer keeps it for the run.
+ */
+export interface ImageDataOp {
+  op: 'imagedata';
+  key: string;
+  width: number;
+  height: number;
+  mime?: string;
+  data?: string | Uint8Array;
+  format?: 'gray' | 'rgba';
+  pixels?: string | Uint8Array;
+}
+
+export type Op = CreateOp | UpdateOp | InsertOp | RemoveOp | CommitOp | DefaultsOp | RequestOp | SwiftDataOp | ImageDataOp;
 
 // ---------------------------------------------------------------------------
 // Events (renderer → Swift)
@@ -806,6 +1227,15 @@ export function isDynamicTypeSize(value: unknown): value is DynamicTypeSize {
 export interface TapEvent {
   type: 'tap';
   id: ElementId;
+  /** A `tapgesture` with `location`: the tap's point in the element's own coordinates. */
+  x?: number;
+  y?: number;
+}
+/** A link run (`TextRun.link`) of a `text` was tapped; `value` is its URL. */
+export interface LinkEvent {
+  type: 'link';
+  id: ElementId;
+  value: string;
 }
 /** A `textfield` or `searchfield` received input. */
 export interface TextEvent {
@@ -875,13 +1305,32 @@ export type RendererEvent =
   | ToggleEvent
   | EnvironmentEvent
   | SelectEvent
+  | LinkEvent
   | GeometryEvent
   | LayoutEvent
   | BatchEvent
   // Phase 8: gestures, rows, navigation (see the block at the end of this file)
   | InteractionEvent
   // Phase 8: alerts, controls (see the block at the end of this file)
-  | Phase8ControlEvent;
+  | Phase8ControlEvent
+  // Phase 13: the answer to a `request` op
+  | ResponseEvent
+  // A `video` element's playback (src/video.ts)
+  | VideoEvent
+  | LazyEvent
+  | MenuEvent;
+
+/**
+ * Phase 13: the page's answer to the `request` op with this `id`: `value`
+ * (a `FetchResult` or `ImageResult` from src/hostRequests.ts) on success,
+ * `error` (a short message the app maps to a `URLError`) on failure.
+ */
+export interface ResponseEvent {
+  type: 'response';
+  id: number;
+  value?: unknown;
+  error?: string;
+}
 
 /**
  * Several events delivered in one `sb_event_json` call: Swift applies each
@@ -948,12 +1397,31 @@ export function isAssetImage(props: ImageProps): props is AssetImageProps {
   return typeof (props as AssetImageProps).name === 'string';
 }
 
+/** True for the bitmap form of `image` props (`{ bitmap, resizable, width, height }`). */
+export function isBitmapImage(props: ImageProps): props is BitmapImageProps {
+  const bitmap = (props as BitmapImageProps).bitmap;
+  return typeof bitmap === 'object' && bitmap !== null;
+}
+
+/** True for the remote form of `image` props (`{ url, resizable, width, height }`, Phase 13). */
+export function isUrlImage(props: ImageProps): props is UrlImageProps {
+  return typeof (props as UrlImageProps).url === 'string';
+}
+
 /** Cheap structural check used when parsing an untrusted JSON buffer. */
 export function isOp(value: unknown): value is Op {
   if (typeof value !== 'object' || value === null) return false;
   const op = (value as { op?: unknown }).op;
   return (
-    op === 'create' || op === 'update' || op === 'insert' || op === 'remove' || op === 'commit' || op === 'defaults'
+    op === 'create' ||
+    op === 'update' ||
+    op === 'insert' ||
+    op === 'remove' ||
+    op === 'commit' ||
+    op === 'defaults' ||
+    op === 'request' ||
+    op === 'swiftdata' ||
+    op === 'imagedata'
   );
 }
 
@@ -1095,6 +1563,8 @@ export interface ChartAxisLabel {
   /** Unit position along the axis (y: 0 is the top). */
   at: number;
   text: string;
+  /** `leading`: an x label that starts at its tick (a date's) instead of centering on it. */
+  anchor?: 'leading';
 }
 /** `null` for the whole axis means hidden. Positions are unit values along the axis. */
 export interface ChartAxis {
@@ -1192,7 +1662,10 @@ export interface SwipeActionsProps {
 }
 
 /** `.contextMenu { }`: `[content, ...items]`; a long press or right click lists the items (as in a `menu`) in a popover. */
-export type ContextMenuProps = Record<string, never>;
+/** As `MenuProps`: `deferred` while the items (every child but the content) are not built. */
+export interface ContextMenuProps {
+  deferred?: boolean;
+}
 
 /**
  * A `List` row that can be selected (`selectable`, `selected`) or deleted
@@ -1235,6 +1708,19 @@ export interface Style {
   hitTesting?: boolean;
 }
 
+export interface Style {
+  /** `.blendMode`: the CSS `mix-blend-mode` the box is composited with. */
+  blendMode?: string;
+  /** `.zIndex(_:)`: the box's CSS `z-index` among its siblings. */
+  zIndex?: number;
+  /**
+   * `.alignmentGuide(_:computeValue:)`: the box's guide `name` on `axis` is
+   * `a + b·width + c·height` (`value: [a, b, c]`), which the containers that
+   * align it by that guide use instead of the default (layout/engine.ts).
+   */
+  alignmentGuide?: { axis: 'horizontal' | 'vertical'; name: string; value: [number, number, number] };
+}
+
 export type DragPhase = 'began' | 'changed' | 'ended' | 'cancelled';
 
 /**
@@ -1325,6 +1811,8 @@ export interface DatePickerProps {
 /** A `<textarea>` filling the proposal; input sends `text` like a `textfield`. */
 export interface TextEditorProps {
   text: string;
+  /** Bound focus (UIKit's `becomeFirstResponder`): the editor takes or gives up focus; `focus` events report changes. */
+  focused?: boolean;
 }
 
 /** A `stepper` half was tapped: +1 or −1. */
@@ -1394,6 +1882,29 @@ export interface Style {
   rotation3D?: Rotation3D;
   /** `.blur(radius:)`: `filter: blur(<radius>px)`, combined with `shadow` in one `filter`. */
   blur?: number;
+  /** `.brightness(_:)`: SwiftUI's amount (-1…1), drawn as CSS `brightness(1 + amount)`. */
+  brightness?: number;
+  /** `.saturation(_:)`: CSS `saturate()`. */
+  saturation?: number;
+  /** `.contrast(_:)`: CSS `contrast()`. */
+  contrast?: number;
+  /** `.grayscale(_:)`: CSS `grayscale()` (0…1). */
+  grayscale?: number;
+  /** `.hueRotation(_:)`: degrees, CSS `hue-rotate()`. */
+  hueRotation?: number;
+  /** `.colorInvert()`: CSS `invert(1)`. */
+  colorInvert?: boolean;
+  /**
+   * `.colorMultiply(_:)`: each component (and the alpha) multiplied by the
+   * color's, drawn with an SVG `feColorMatrix` filter (colorMultiply.ts).
+   */
+  colorMultiply?: Color;
+  /** View `.underline(_:)`: underlines the texts below (false turns an ancestor's off). */
+  underline?: boolean;
+  /** View `.strikethrough(_:)`: strikes the texts below through (false turns it off). */
+  strikethrough?: boolean;
+  /** View `.italic(_:)`: slants the texts below (false turns it off). */
+  italic?: boolean;
   /**
    * `.ignoresSafeArea(edges:)`: the engine extends the box to the screen
    * edge on each listed side when the box touches that safe-area edge. The
@@ -1419,3 +1930,241 @@ export type ScenePhase = 'active' | 'inactive' | 'background';
 export interface EnvironmentEvent {
   scenePhase?: ScenePhase;
 }
+
+// ---------------------------------------------------------------------------
+// Multi-line text fields, view section headers, scrolling to a view
+// ---------------------------------------------------------------------------
+
+export interface TextFieldProps {
+  /**
+   * `TextField(_:text:axis: .vertical)`: a `<textarea>` that grows with its
+   * text between the enclosing `lineLimitMin` (1) and `lineLimit` (none)
+   * lines and scrolls past that; Return breaks the line unless the field has
+   * `submit` (then Shift-Return does). Absent for a one-line field.
+   */
+  axis?: 'vertical';
+}
+
+export interface ListProps {
+  /** `.scrollContentBackground(.hidden)`: the list draws no background of its own (rows keep theirs). */
+  background?: 'hidden';
+  /** `.scrollDismissesKeyboard(.immediately | .interactively)`: scrolling blurs the text input being edited inside. */
+  dismissesKeyboard?: boolean;
+}
+
+export interface ScrollViewProps {
+  /** As for `list`. */
+  dismissesKeyboard?: boolean;
+}
+
+/**
+ * A `Section`'s header or footer that is a view rather than a `Text`: the
+ * first (`sectionheader`) or last (`sectionfooter`) child of the `section`,
+ * holding the view. In a list it sits above / below the section's card in
+ * the content width (footnote font, secondary color); elsewhere it stacks
+ * with the rows.
+ */
+export type SectionSupplementProps = Record<string, never>;
+
+export interface ElementPropsByKind {
+  sectionheader: SectionSupplementProps;
+  sectionfooter: SectionSupplementProps;
+}
+
+/** `ScrollViewProxy.scrollTo(_:anchor:)`: where the target should end up (null: as little scrolling as shows it). */
+export interface ScrollToCommand {
+  anchor: UnitPoint | null;
+  /** Increases with every request (across readers); the page carries out each serial once. */
+  serial: number;
+}
+
+export interface Style {
+  /** `.id(_:)` inside a `ScrollViewReader`: this box is a scroll target. */
+  scrollID?: boolean;
+  /**
+   * Set in the pass in which a `ScrollViewProxy` asks to scroll to this box
+   * (and kept until the reader re-runs): after laying out a pass that brings
+   * a serial above every one it handled, the page scrolls the scroll views
+   * and lists around it (smoothly when the pass's commit is animated).
+   */
+  scrollTo?: ScrollToCommand;
+  /** The lower bound of a `.lineLimit(2...4)` range (absent for 1): a vertical text field's minimum lines. */
+  lineLimitMin?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Video and audio (docs/ops-protocol.md, "Video and audio")
+// ---------------------------------------------------------------------------
+
+/**
+ * A `video` element: an `AVPlayer` shown by a view (AVKit's `VideoPlayer`, an
+ * `AVPlayerLayer`), as an HTML `<video>` (src/video.ts). No children.
+ */
+/**
+ * Lazy rows: the rows of a `List` or lazy stack that are not built yet
+ * (`remaining` of them, after the built ones). It takes no space; when it
+ * comes within a screen of its scroll view's visible area the page sends a
+ * `lazy` event, and Swift builds the next rows (a new spacer follows them).
+ */
+export interface LazySpacerProps {
+  axis: 'vertical' | 'horizontal';
+  remaining: number;
+}
+
+/** Lazy menus: the viewer opened (`open: true`) or closed a deferred `menu` / `contextmenu`. */
+export interface MenuEvent {
+  type: 'menu';
+  id: ElementId;
+  open: boolean;
+}
+
+/** A `lazyspacer` came near the visible area: build the next rows. */
+export interface LazyEvent {
+  type: 'lazy';
+  id: ElementId;
+}
+
+export interface VideoProps {
+  /** The media URL (remote, data or blob); null while there is none. */
+  url: string | null;
+  /** Whether the player plays here (only the newest view of a player plays it). */
+  playing: boolean;
+  muted: boolean;
+  /** 0…1. */
+  volume: number;
+  /** The playback rate (positive; the player's default rate while paused). */
+  rate: number;
+  /** An `AVPlayerLooper` loops the item. */
+  loop: boolean;
+  /** CSS `object-fit`: `contain`, `cover`, `fill`. */
+  gravity: 'resizeAspect' | 'resizeAspectFill' | 'resize';
+  /** The browser's native playback controls (`VideoPlayer`, `AVPlayerViewController`). */
+  controls: boolean;
+  /** Seconds; the page seeks once per serial (and reports `seeked` with it). */
+  seek: { time: number; serial: number };
+  /** Report the position this often (seconds) while playing, when shorter than `timeupdate`'s pace. */
+  report?: number;
+  /** The video's size in pixels, once known: the aspect ratio of an axis left open. */
+  width?: number;
+  height?: number;
+}
+
+export interface ElementPropsByKind {
+  video: VideoProps;
+  lazyspacer: LazySpacerProps;
+}
+
+/**
+ * A gradient of a `Canvas` (`GraphicsContext.Shading`), in the drawing's own
+ * coordinates (points, after the command's `transform`) rather than the
+ * unit square of a view's box.
+ */
+export interface CanvasLinearGradientShading {
+  canvasLinearGradient: { stops: GradientStop[]; start: { x: number; y: number }; end: { x: number; y: number } };
+}
+export interface CanvasRadialGradientShading {
+  canvasRadialGradient: { stops: GradientStop[]; center: { x: number; y: number }; startRadius: number; endRadius: number };
+}
+export type CanvasShading = ShapeStyle | CanvasLinearGradientShading | CanvasRadialGradientShading;
+
+/** A `GraphicsContext.Filter`: one key, its amount (degrees for `hueRotation`). */
+export type CanvasFilter =
+  | { blur: number }
+  | { shadow: { color: Color; radius: number; x: number; y: number } }
+  | { grayscale: number }
+  | { saturation: number }
+  | { brightness: number }
+  | { contrast: number }
+  | { hueRotation: number }
+  | { invert: number };
+
+/** The context's state when a command was drawn. */
+export interface CanvasState {
+  /** `[a, b, c, d, tx, ty]`, as `CGAffineTransform` (and SVG's `matrix()`); absent for the identity. */
+  transform?: [number, number, number, number, number, number];
+  opacity?: number;
+  /** CSS `mix-blend-mode`. */
+  blendMode?: string;
+  /** SVG path data, in the canvas's coordinates; the command draws inside all of them. */
+  clips?: string[];
+  filters?: CanvasFilter[];
+}
+
+export type CanvasCommand = CanvasState &
+  (
+    | { op: 'fill'; path: string; shading: CanvasShading; evenOdd?: boolean }
+    | {
+        op: 'stroke';
+        path: string;
+        shading: CanvasShading;
+        lineWidth: number;
+        lineCap?: 'butt' | 'round' | 'square';
+        lineJoin?: 'miter' | 'round' | 'bevel';
+        miterLimit?: number;
+        dash?: number[];
+        dashPhase?: number;
+      }
+    | {
+        op: 'image';
+        image: ImageProps;
+        /** The point `anchor` (a unit point of the image) is placed at. */
+        x: number;
+        y: number;
+        anchor: UnitPoint;
+        /** `draw(_:in:)`: the rectangle's size; otherwise the image's own size. */
+        width?: number;
+        height?: number;
+        /** A resolved image's `shading`: a template image is painted with it. */
+        shading?: CanvasShading;
+      }
+    | { op: 'text'; text: string; x: number; y: number; anchor: UnitPoint; shading: CanvasShading; font?: Font }
+  );
+
+/**
+ * A `Canvas` at one size (src/canvasDrawing.ts): the commands its renderer
+ * drew for `width` × `height`, the size the canvas reported. It fills its
+ * proposal and clips the drawing to its box.
+ */
+export interface CanvasProps {
+  width: number;
+  height: number;
+  commands: CanvasCommand[];
+}
+
+export interface ElementPropsByKind {
+  canvas: CanvasProps;
+}
+
+/**
+ * What a `video` element reports: `ready` (metadata), `time`, `status`
+ * (playing, waiting, paused), `seeked` (a `seek` serial done), `play` /
+ * `pause` (the viewer used the controls; `reason: "blocked"` when the browser
+ * refused to start), `volume`, `rate`, `ended`, `error` (a `MediaError` code).
+ */
+export interface VideoEvent {
+  type: 'video';
+  id: ElementId;
+  event: 'ready' | 'time' | 'status' | 'seeked' | 'play' | 'pause' | 'volume' | 'rate' | 'ended' | 'error';
+  url?: string;
+  time?: number;
+  duration?: number | null;
+  width?: number;
+  height?: number;
+  status?: 'playing' | 'waiting' | 'paused';
+  serial?: number;
+  reason?: 'blocked';
+  muted?: boolean;
+  volume?: number;
+  rate?: number;
+  code?: number;
+  message?: string;
+}
+
+/** `media` requests (src/media.ts): AVFoundation's files and probes, QuickLook's previews. */
+export interface MediaRequestParams {
+  action: 'file' | 'probe' | 'release' | 'open';
+  url?: string;
+  name?: string;
+  type?: string;
+  data?: string;
+}