@wix/agent-skills 1.16.3 → 1.17.0

package/skills/wix-app/references/editor-react-component/DESIGN-STATES.md

@@ -1,11 +1,21 @@
 # Design States
 
-A design state styles an element differently per interaction (`hover`,
-`focus`, `disabled`, `invalid`) or per a selectable value in its data
-(`selected`, `active`, `open`, …). Author states in the component's `.tsx`
-and `.module.css`.
+Use this reference when a named part changes appearance through interaction or
+a selectable value. A design state styles an element differently for an
+eligible interaction (`hover`, `focus`, `disabled`, `invalid`) or per a
+selectable value in its data (`selected`, `active`, `open`, …). Author states
+in the component's `.tsx` and `.module.css`.
 
-## 1. Which states each element supports
+## Contents
+
+- [Choose Supported States](#1-choose-supported-states)
+- [Name the State Class](#2-name-the-state-class)
+- [Author CSS](#3-author-css)
+- [Wire React](#4-wire-react)
+- [Use Prop-Triggered States on the Root Only](#5-use-prop-triggered-states-on-the-root-only)
+- [Checklist](#checklist)
+
+## 1. Choose Supported States
 
 | Element | Author these states |
 |---|---|
@@ -17,43 +27,37 @@ and `.module.css`.
 | None of the above | no states — resting style only |
 
 An explicit `role` overrides the tag's implicit semantics: `<input role="button">`
-is a non-input control, and `<div role="checkbox">` is an input field.
+is a non-input control, while `<div role="checkbox">` is an input field.
 
 A `focus` design state is an editor styling control, not the keyboard focus
 indicator itself. Do not add a global `--focus` modifier to a non-input control
-unless the user explicitly asks for an editable focus state. A control that
-restyles its own `outline`, `background`, or `border` MUST still carry a
-standalone `:focus-visible` rule — that rule is its only keyboard affordance.
+unless the user explicitly requests editable focus styling. A control that
+restyles its own outline, background, or border must still carry a standalone
+`:focus-visible` rule as its keyboard affordance.
 
 A custom state may also be driven by a root-level boolean prop (e.g.
-`isFeatured`) instead of by markup or item data — see §5.
+`isFeatured`) instead of by markup or item data — see §5. For an active-item
+component, drive each item's `--active` class by comparing its index with the
+active-index prop rather than storing a per-item boolean.
 
-For **active-item components** (tabs, slideshow, steps), the `--active` state on
-each item is driven by comparing the item's index to the active-index prop
-(`index === activeItem`), not by a per-item boolean flag — see
-[Active-item components](COMPONENT-API.md#active-item-components-one-body-visible-at-a-time)
-in [`COMPONENT-API.md`](COMPONENT-API.md).
-
-## 2. Name the state class
+## 2. Name the State Class
 
 Flat: the element's own global class + `--<state>`. Because inner-part
-global classes are prefixed with the component name (see
-[`CSS-GUIDELINES.md`](CSS-GUIDELINES.md)), the state class is prefixed too —
+global classes are prefixed with the component name, the state class is prefixed too —
 e.g. `pricing-card-cta--hover`, `pricing-card-plan-row--selected`. Never bare
 (`cta--hover` would collide with other components on the page) and never
 nested (`card__row--selected`).
 
-## 3. CSS
+## 3. Author CSS
 
 Put the resting value in the bare class; put only the state override in the
 state selector.
 
 - **Native design state** — pair the pseudo-class with the `:global` modifier.
   Every exposed native state needs both selectors in the same rule; do not
-  split the pair across states (for example, pseudo-only `hover` plus
-  global-only `disabled`). A standalone `:focus-visible` accessibility rule on
-  a non-input control is intentionally not an editor design state and therefore
-  has no `:global` modifier.
+  split the pair across states. A standalone `:focus-visible` accessibility
+  rule on a non-input control is not an editor design state and has no global
+  modifier.
 - **Custom** — the `:global` modifier alone.
 
 The bare selector is the short **module** class (`.cta`); the `:global(...)`
@@ -79,10 +83,11 @@ state class is the **prefixed** global one.
 }
 ```
 
-## 4. React
+## 4. Wire React
 
 - **Native** — render the correct interactive element (`<button>`, an
-  interactive `role`, or a handler). Nothing else needed.
+  interactive `role`, or a handler). No custom state class is needed, but the
+  element must still satisfy the accessibility contract for its semantics.
 - **Custom** — toggle the global state class from the element's data.
 - **Inner elements** — every named inner element gets an `elementProps` entry;
   spread it so editor-driven states reach it. On a raw HTML element also merge
@@ -90,7 +95,8 @@ state class is the **prefixed** global one.
   spread alone suffices (it merges `className` itself). The `elementProps` key
   stays the **short** part name (`cta`) even though the element's global class
   is prefixed (`pricing-card-cta`) — don't rename the key to match the class.
-  See [`COMPONENT-API.md`](COMPONENT-API.md).
+
+Wire native and custom states as follows:
 
 ```tsx
 <button
@@ -101,12 +107,20 @@ state class is the **prefixed** global one.
   {label}
 </button>
 
-<li className={classNames('pricing-card-plan-row', styles.planRow, row.selected && 'pricing-card-plan-row--selected')}>
+<li
+  {...elementProps?.planRow}
+  className={classNames(
+    'pricing-card-plan-row',
+    styles.planRow,
+    row.selected && 'pricing-card-plan-row--selected',
+    elementProps?.planRow?.className,
+  )}
+>
   {row.label}
 </li>
 ```
 
-## 5. Prop-triggered states (root only)
+## 5. Use Prop-Triggered States on the Root Only
 
 A **prop-triggered** state is a custom state switched by a single boolean
 **prop**, rather than by interactive markup (native) or a per-item data flag
@@ -150,3 +164,13 @@ Rules:
 Prefer a native state (interactive markup) or a class trigger (per-item data
 such as `row.selected`) whenever one fits — those are the common cases and work
 at any depth. Reach for a prop trigger only for a root-level boolean switch.
+
+## Checklist
+
+- [ ] Each named part declares only states its semantics or data supports.
+- [ ] Eligible native design-state selectors pair the pseudo-class with the
+      prefixed global modifier.
+- [ ] Non-input controls retain a standalone `:focus-visible` keyboard indicator.
+- [ ] Custom state classes are flat, global, and prefixed by component and part.
+- [ ] Named inner parts spread and merge their `elementProps` entry.
+- [ ] `ElementState<boolean>` is used only for a component-level root state.

package/skills/wix-app/references/editor-react-component/DIRECTIONALITY.md

@@ -1,187 +1,82 @@
-# Component Directionality (RTL/LTR)
+# Directionality (RTL/LTR)
 
-Rules and patterns for direction support in Editor React components.
+Use these rules for component direction, logical layout, nested content, and
+direction-dependent JavaScript.
 
----
+## Contents
 
-## Rules
+- [Root Contract](#root-contract)
+- [Logical CSS](#logical-css)
+- [Direction-Dependent Transforms](#direction-dependent-transforms)
+- [Direction-Dependent JavaScript](#direction-dependent-javascript)
+- [Nested `ReactNode` Content](#nested-reactnode-content)
+- [Checklist](#checklist)
 
-Direction support is mandatory for every component. The pattern uses native HTML `dir` attributes for standards-compliant, accessible directionality support, with mandatory fallback classes on root components.
+## Root Contract
 
-### Direction Resolution
+Every component accepts `direction?: Direction`. Put `dir={direction}` and the
+fallback class on the elected root; do not add a wrapper for them. Apply the
+fallback class unconditionally so it works whenever `dir` is absent. Preserve
+the scaffolded `dir`, root class, and `.fallbackDirection:not([dir])` wiring;
+the generated component already demonstrates this contract.
 
-```typescript
-const subComponentDirection = elementProps?.subComponent?.direction;
-```
-
-- Sub-component directions only applied when explicitly set (to override inherited direction)
-- When undefined: inherits direction from parent via CSS inheritance
-- Root component always gets fallback class
-
-### Direction Anti-Patterns
-
-```scss
-/* ❌ Don't use CSS variables for direction */
-.component { direction: var(--component-direction, ltr); }
-```
-
-```tsx
-/* ❌ Don't use conditional logic for fallback class */
-className={classNames({
-  [styles.fallbackDirection]: !direction
-})}
-```
+Do not set fallback direction with a React condition or a custom direction CSS
+variable.
 
-### RTL in SCSS
+## Logical CSS
 
-Use logical CSS properties — never physical `left`/`right`-only layouts. See §2.1 below.
+Use logical inline-axis properties instead of physical left/right properties:
 
----
-
-## Patterns
-
-### Root Element Pattern
-
-Apply on main component only. `dir` and the fallback class go on whatever element is the root — never add a wrapper `<div>` to host them (see [`PARTS.md`](PARTS.md) Step 0).
-
-```typescript
-<div
-  id={id}
-  dir={direction}
-  className={classNames(
-    'profile-card',
-    styles.root,
-    className,
-    styles.fallbackDirection,
-  )}
->
-```
-
-```typescript
-/* Root is the component's own semantic element — same attribute, same classes */
-<button
-  type="button"
-  id={id}
-  dir={direction}
-  className={classNames(
-    'like-button',
-    styles.root,
-    className,
-    styles.fallbackDirection,
-  )}
->
-```
-
-```scss
-.fallbackDirection:not([dir]) {
-  direction: var(--wix-opt-in-direction);
+```css
+.element {
+  inset-inline-start: 0;
+  padding-inline-start: 8px;
+  margin-inline-end: 4px;
+  border-inline-end: 1px solid currentColor;
 }
 ```
 
-**Imports:**
-
-```typescript
-import type { Direction } from '@wix/editor-react-types';
-```
-
-### Child Element Direction
-
-Only when explicitly specified:
-
-```typescript
-const labelDirection = elementProps?.label?.direction;
-
-<span
-  dir={labelDirection}
->
-```
-
-### Runtime Direction Checking
-
-**Site direction hook:**
-
-Use the hook **only** when direction drives JavaScript behavior (keyboard navigation, animation logic, conditional rendering). For purely visual RTL, use logical CSS properties instead — see below.
-
-```typescript
-import { useLanguageDirection } from '@wix/react-component-utils';
-
-const siteDirection = useLanguageDirection();
-const isRTL = siteDirection === 'rtl';
-```
-
-See [`SITE-CONTEXT-HOOKS.md`](SITE-CONTEXT-HOOKS.md) for the full set of site context hooks.
+Block-axis properties such as `top`, `bottom`, and `padding-block` do not need
+directional conversion.
 
-**Fallback chain (for child components):**
+## Direction-Dependent Transforms
 
-```typescript
-const isRTL = (direction || parentDirection || siteDirection) === 'rtl';
-```
-
-**CSS Variable**
+For directional transforms, use the platform multiplier:
 
-Use css variable `--wix-opt-in-direction-multiplier` when direction only affects visual appearance (transforms, spacing, layout):
-
-```scss
-.scrollButton {
+```css
+.arrow {
   scale: var(--wix-opt-in-direction-multiplier, 1) 1;
 }
 ```
 
-### RTL Support — Use Logical CSS Properties
+## Direction-Dependent JavaScript
 
-**✅ Correct:**
+Use `useLanguageDirection()` only when direction changes JavaScript behavior,
+such as arrow-key order, scroll math, animation direction, or conditional
+rendering. Purely visual direction belongs in logical CSS.
 
-```scss
-.element {
-  inset-inline-start: 0; // Instead of left
-  inset-inline-end: 0; // Instead of right
-  padding-inline-start: 8px; // Instead of padding-left
-  margin-inline-end: 4px; // Instead of margin-right
-}
-```
-
-**❌ Wrong:**
+```tsx
+import { useLanguageDirection } from '@wix/react-component-utils';
 
-```scss
-.element {
-  padding-left: 8px;
-  [dir='rtl'] & {
-    padding-right: 8px; // Manual RTL - avoid
-  }
-}
+const siteDirection = useLanguageDirection();
+const resolvedDirection = direction ?? siteDirection;
+const isRtl = resolvedDirection === 'rtl';
 ```
 
-Use logical CSS properties (e.g., `margin-inline-start` not `margin-left`) for RTL support.
-
----
-
-## Common Mistake: Manual RTL Handling
-
-**❌ Wrong:**
-
-```scss
-.element {
-  padding-left: 8px;
-  [dir='rtl'] & {
-    padding-right: 8px; // Manual overrides
-  }
-}
-```
+## Nested `ReactNode` Content
 
-**✅ Correct:**
+Put `dir="ltr"` on the element that renders a `ReactNode` content prop. This
+isolates arbitrary nested content from the parent component's direction so each
+nested component can resolve its own contract.
 
-```scss
-.element {
-  padding-inline-start: 8px; // Auto RTL/LTR
-}
+```tsx
+<div dir="ltr">{item.content}</div>
 ```
 
-## Container Components and RTL Inheritance
+## Checklist
 
-Elements that render `React.ReactNode` content MUST have `dir="ltr"` to prevent RTL inheritance from the parent component:
-
-```tsx
-<Accordion.Content dir="ltr">
-  {item.content} {/* React.ReactNode */}
-</Accordion.Content>
-```
+- [ ] Root props include `direction?: Direction`.
+- [ ] The elected root has `dir={direction}` and the unconditional fallback class.
+- [ ] Direction-sensitive CSS uses logical properties.
+- [ ] Runtime direction hooks are used only for JavaScript behavior.
+- [ ] Every `ReactNode` content slot renders under `dir="ltr"`.

package/skills/wix-app/references/editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md

@@ -0,0 +1,78 @@
+# Editor Extension Configuration
+
+Use this reference to edit `<component-name>.extension.ts` after scaffolding and
+before the final build. Preserve the scaffold's generated editor element,
+client and editor resources, merge order, and defaults wiring. Manifest
+generation rewrites
+`<component-name>.generated.ts`; it does not rewrite the extension file.
+
+For a new component, complete the scaffolded installation and layout fields.
+For an existing component, change only the sizing, installation, or manifest
+behavior requested by the user; preserve every other extension field.
+
+## Contents
+
+- [Preserve the Extension Shape](#preserve-the-extension-shape)
+- [Choose Initial Height](#choose-initial-height)
+- [Choose Resize Direction](#choose-resize-direction)
+- [Checklist](#checklist)
+
+## Preserve the Extension Shape
+
+For a new component, the extension should continue to:
+
+- import `editorElement` from `<component-name>.generated.ts`
+- load `component.tsx?url` for the client and `component.preview.tsx?url` for
+  the editor
+- apply `defaultProps` from `<component-name>.props.ts` through
+  `withEditorElementDefaults`
+- merge layout overrides into the editor element after applying defaults
+
+For an existing component, preserve its generated export shape. Older
+extensions may import and spread `manifest.editorElement` and
+`manifest.resources`; do not migrate that wiring during an unrelated edit.
+
+Preserve the generated `defaultProps` import from `./<component-name>.props`.
+That file remains the single source of truth.
+
+## Choose Initial Height
+
+Determine from the component contract whether its own content decides its
+height. Ask the user only when the requested behavior leaves this materially
+ambiguous.
+
+| Answer | Sizing type |
+| --- | --- |
+| Text or nested content should grow the component | `LAYOUT.SIZING_TYPE.content`; omit `pixels` |
+| The component is a framed visual/control with a natural fixed height | `LAYOUT.SIZING_TYPE.pixels`; provide `pixels` |
+
+Tiebreaker: if a designer should drag a height handle, use `pixels`; if height
+should fit content, use `content`.
+
+## Choose Resize Direction
+
+Allow an axis only when dragging it produces a meaningful result.
+
+| Value | Use when |
+| --- | --- |
+| `horizontalAndVertical` | Content meaningfully fills both axes; default for framed visuals and most layouts |
+| `horizontal` | Height is intrinsic or intentionally rigid |
+| `vertical` | Width is intrinsic or intentionally rigid |
+| `aspectRatio` | Distortion would break the component's identity |
+| `none` | A parent fully owns size; do not use for a top-level component |
+
+Edit the scaffolded `layout`, `installation`, and `resources` fields in place;
+do not reconstruct the extension from an example. For a new component, add
+`staticContainer: 'HOMEPAGE'`. For an existing component, preserve its current
+`staticContainer` value unless the request explicitly changes installation
+behavior.
+
+## Checklist
+
+- [ ] Defaults are applied to the generated editor element before layout
+      overrides are merged.
+- [ ] Client and editor resources still point to their generated entry files.
+- [ ] The extension and `component.tsx` consume the same `defaultProps` source.
+- [ ] Initial sizing and resize axes match component behavior.
+- [ ] A new component has `staticContainer: 'HOMEPAGE'`; an existing
+      component keeps its prior installation behavior unless explicitly changed.

package/skills/wix-app/references/editor-react-component/FUNCTION-HANDLERS.md

@@ -1,167 +1,75 @@
-# Function Event Handlers
+# Function Handlers
 
-Rules and patterns for adding function event handler props to an Editor React component's TypeScript interface, wiring them to DOM events, and declaring custom callbacks.
+Use this reference only when the component specification exposes callbacks to
+site owners. Keep implementation-only handlers out of the public props type.
 
----
+## Standard SDK Handlers
 
-## Rules
+Use the exact SDK prop name and wire it to the matching React DOM event.
 
-### Standard SDK Event Handlers
+| SDK prop | React DOM prop | Type |
+| --- | --- | --- |
+| `onClick` | `onClick` | `(event: React.MouseEvent) => void` |
+| `onDblClick` | `onDoubleClick` | `(event: React.MouseEvent) => void` |
+| `onChange` | `onChange` | `(event: React.ChangeEvent<HTMLElement>) => void` |
+| `onFocus` | `onFocus` | `(event: React.FocusEvent) => void` |
+| `onBlur` | `onBlur` | `(event: React.FocusEvent) => void` |
+| `onMouseIn` | `onMouseEnter` | `(event: React.MouseEvent) => void` |
+| `onMouseOut` | `onMouseLeave` | `(event: React.MouseEvent) => void` |
 
-These are the standard event handler props the editor SDK exposes to site owners. Use the exact prop names — ZeroConfig and the manifest system recognize them.
+Declare only the handlers the component actually exposes.
 
-| Prop name    | React DOM event | Type                                             |
-| ------------ | --------------- | ------------------------------------------------ |
-| `onClick`    | `onClick`       | `(event: React.MouseEvent) => void`              |
-| `onDblClick` | `onDoubleClick` | `(event: React.MouseEvent) => void`              |
-| `onChange`   | `onChange`      | `(event: React.ChangeEvent<HTMLElement>) => void` |
-| `onFocus`    | `onFocus`       | `(event: React.FocusEvent) => void`              |
-| `onBlur`     | `onBlur`        | `(event: React.FocusEvent) => void`              |
-| `onMouseIn`  | `onMouseEnter`  | `(event: React.MouseEvent) => void`              |
-| `onMouseOut` | `onMouseLeave`  | `(event: React.MouseEvent) => void`              |
-
-Three props have a **name mismatch** between the SDK prop and the DOM event: `onDblClick` → `onDoubleClick`, `onMouseIn` → `onMouseEnter`, `onMouseOut` → `onMouseLeave`.
-
-### Declaring Standard Handler Props
-
-Declare standard handlers inline with the exact SDK prop names and React event types:
-
-```typescript
-interface MyComponentProps {
-  label?: string;
+```tsx
+export type ActionProps = {
   onClick?: (event: React.MouseEvent) => void;
   onDblClick?: (event: React.MouseEvent) => void;
-  onChange?: (event: React.ChangeEvent<HTMLElement>) => void;
-  onFocus?: (event: React.FocusEvent) => void;
-  onBlur?: (event: React.FocusEvent) => void;
   onMouseIn?: (event: React.MouseEvent) => void;
   onMouseOut?: (event: React.MouseEvent) => void;
-}
-```
-
-Only declare handlers the component actually exposes. Do not add all seven if the component only handles two.
-
-### Wiring Standard Handlers to DOM Events
+};
 
-Destructure the props and pass them to the correct DOM event — applying the name mappings:
+export const Action: React.FC<ActionProps> = (props) => {
+  const { onClick, onDblClick, onMouseIn, onMouseOut } = props;
 
-```typescript
-export const MyComponent = (props: MyComponentProps) => {
-  const { onClick, onDblClick, onFocus, onBlur, onMouseIn, onMouseOut } = props;
   return (
-    <div
+    <button
+      type="button"
       onClick={onClick}
       onDoubleClick={onDblClick}
-      onFocus={onFocus}
-      onBlur={onBlur}
       onMouseEnter={onMouseIn}
       onMouseLeave={onMouseOut}
-    >
-      {/* ... */}
-    </div>
+    />
   );
 };
 ```
 
-### Custom Callbacks
+Do not expose DOM names such as `onDoubleClick`, `onMouseEnter`, or
+`onMouseLeave` in the component API; zero config recognizes the SDK names.
 
-Component-specific callbacks that do not correspond to a DOM event (e.g., `onPlay`, `onPause`, `onEnded`, `onTimeupdate`) are **not** standard SDK event handlers. Type them as `() => void` — no React event parameter:
+## Custom Callbacks
 
-```typescript
-interface VideoPlayerProps {
+A component-level notification that is not one of the standard SDK DOM events
+uses `() => void` unless the component contract explicitly defines a serializable
+payload. Do not expose a React synthetic event for custom callbacks.
+
+Use this pattern:
+
+```tsx
+export type VideoPlayerProps = {
   onPlay?: () => void;
   onPause?: () => void;
   onEnded?: () => void;
-}
-```
-
-Pass them directly to the underlying element — no name remapping needed:
+};
 
-```typescript
-export const VideoPlayer = (props: VideoPlayerProps) => {
+export const VideoPlayer: React.FC<VideoPlayerProps> = (props) => {
   const { onPlay, onPause, onEnded } = props;
   return <video onPlay={onPlay} onPause={onPause} onEnded={onEnded} />;
 };
 ```
 
----
-
-## Common Mistakes
-
-### Passing SDK prop name directly to DOM instead of remapping
-
-**❌ Wrong:**
-
-```typescript
-export const MyComponent = (props: MyComponentProps) => {
-  const { onMouseIn, onMouseOut, onDblClick } = props;
-  return (
-    <div
-      onMouseIn={onMouseIn} // ❌ not a valid React DOM prop
-      onMouseOut={onMouseOut} // ❌ not a valid React DOM prop
-      onDblClick={onDblClick} // ❌ not a valid React DOM prop
-    />
-  );
-};
-```
-
-**✅ Correct:**
-
-```typescript
-export const MyComponent = (props: MyComponentProps) => {
-  const { onMouseIn, onMouseOut, onDblClick } = props;
-  return (
-    <div
-      onMouseEnter={onMouseIn} // ✅ onMouseIn → onMouseEnter
-      onMouseLeave={onMouseOut} // ✅ onMouseOut → onMouseLeave
-      onDoubleClick={onDblClick} // ✅ onDblClick → onDoubleClick
-    />
-  );
-};
-```
-
-### Adding a React event parameter to custom callbacks
-
-**❌ Wrong:**
-
-```typescript
-interface VideoPlayerProps {
-  onPlay?: (event: React.SyntheticEvent) => void; // ❌ event param on custom callback
-  onEnded?: (event: React.SyntheticEvent) => void; // ❌ event param on custom callback
-}
-```
-
-**✅ Correct:**
-
-```typescript
-interface VideoPlayerProps {
-  onPlay?: () => void; // ✅ no event param
-  onEnded?: () => void; // ✅ no event param
-}
-```
-
-**Why:** Custom callbacks are component-level notifications to the site owner, not DOM event forwarders. They carry no event object — the SDK passes no event to them.
-
-### Using the DOM event name as the SDK prop name
-
-**❌ Wrong:**
-
-```typescript
-interface MyComponentProps {
-  onDoubleClick?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
-  onMouseEnter?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
-  onMouseLeave?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
-}
-```
-
-**✅ Correct:**
-
-```typescript
-interface MyComponentProps {
-  onDblClick?: (event: React.MouseEvent) => void; // ✅ SDK prop name
-  onMouseIn?: (event: React.MouseEvent) => void; // ✅ SDK prop name
-  onMouseOut?: (event: React.MouseEvent) => void; // ✅ SDK prop name
-}
-```
+## Checklist
 
-**Why:** The SDK prop names (`onDblClick`, `onMouseIn`, `onMouseOut`) are what ZeroConfig and the manifest system register. Using DOM names breaks the editor's event wiring.
+- [ ] The specification explicitly requires each public callback.
+- [ ] Standard handler names match the SDK contract exactly.
+- [ ] Mismatched SDK/DOM names are mapped at the rendered element.
+- [ ] Custom callbacks do not leak React event objects.
+- [ ] Internal handlers remain implementation details.