@roku-sdk/ai 0.0.0-stage → 2.19.0

package/skills/flex-grid/references/focus-integration.md

@@ -0,0 +1,355 @@
+# Focus Integration
+
+A grid is in one of two modes, and the mode decides everything about how keys reach it. One
+config field selects it.
+
+| `focusId` | Mode | How keys arrive |
+|---|---|---|
+| passed | **top-level** | The grid renders its own nested `FocusBoundary` and claims seven keys from the enclosing boundary — the four movement keys, `OK`, `fastforward` and `rewind` |
+| omitted | **bare** (nested in another grid's cell) | No boundary exists. The parent cell's `KeyDelegate` calls `handle.forwardKeyEvent(key, press)` |
+
+Nothing else distinguishes them: same config, same handle, same plugins.
+
+## Top-level: hand focus to a sibling region at an edge
+
+The grid claims `left`, `right`, `up`, `down`, `OK`, `fastforward` and `rewind`, and nothing
+else — a key outside that set bubbles to the enclosing boundary untouched, which is how a
+screen's `back` still works. By default a claimed key is consumed whether or not it moved
+anything, so the enclosing `onUnhandledKey` never sees one; `declineUnhandledNavigation: true`
+changes that, and is covered under nested grids below, where it matters most. Those are the runtime strings the firmware delivers, which is what
+`handleAdditionalKeyEvents` is compared against; the enum members for the last two are spelled
+`RemoteKey.Fwd` and `RemoteKey.Rev`. Add to the set with `handleAdditionalKeyEvents`, and catch
+what the grid then does not use with `onUnhandledAdditionalKey`; both are top-level concerns and
+neither exists in bare mode. The list is filtered against the seven above, so naming one of them
+there is dropped rather than rejected — a caller cannot re-route a navigation key and break the
+grid.
+
+`onEdgeReached` is the region hand-off cue. Its return is the half that reads the other way round
+from most APIs:
+
+| | |
+|---|---|
+| Signature | `onEdgeReached?: (edge: PositionValue) => void` |
+| The argument | One of `"top"`, `"bottom"`, `"left"`, `"right"`. `PositionValue` aliases the `Position` string enum, whose members hold exactly those strings, so `edge === "top"` and `edge === Position.Top` both compile and both match. Both names are exported from 2.15.0 on, and an install older than that types the argument as the bare literal union — so comparing against the literals is the form that holds on every version |
+| The return | `void`. There is no consume signal — returning `true` is meaningless, and the key is already spent |
+| When it fires | The user was **already** at that boundary and pressed further. Never on a wrap, and never on a press that moved focus |
+
+So moving focus is your call to make, and the only thing the grid promises is the report.
+
+```tsx rsg-skill=complete
+import { Group, Label, Rectangle } from "@roku-sdk/components";
+import type { CellRenderProps } from "@roku-sdk/flex-grid";
+import { defineFlexGrid, fixedFocusStrategy, floatingFocusYStrategy } from "@roku-sdk/flex-grid";
+import { FocusBoundary, useFocusable, useFocusActions } from "@roku-sdk/navigation";
+import { type Component, onCleanup } from "@roku-sdk/solid";
+
+interface Card {
+    title: string;
+}
+
+const screenId: object = {};
+const navId: object = {};
+const gridId: object = {};
+const firstTabId: object = {};
+
+const Shelf = defineFlexGrid<Card>();
+
+const CardCell: Component<CellRenderProps<Card>> = props => (
+    <group>
+        <rectangle
+            width={props.width}
+            height={props.height}
+            color={props.focused() ? "0x0055FFFF" : "0x1A1A1AFF"}
+        />
+        <label text={props.item?.title ?? "…"} translation={[16, 120]} />
+    </group>
+);
+
+function cardCellComponent(): Component<CellRenderProps<Card>> {
+    return CardCell;
+}
+
+function NavTab(props: { label: string; focusId?: object; x: number }) {
+    const { ref, isFocused } = useFocusable({ focusId: props.focusId });
+
+    return (
+        <group ref={ref} translation={[props.x, 0]}>
+            <rectangle width={200} height={56} color={isFocused() ? "0x0055FFFF" : "0x1A1A1AFF"} />
+            <label text={props.label} translation={[16, 16]} />
+        </group>
+    );
+}
+
+/** Rendered inside the screen's boundary, which is what makes both regions reachable. */
+export const ShelfScreen: Component = () => {
+    // Written by the capture component, read by the edge callback.
+    let focusRegion: ((id: object) => void) | undefined;
+
+    const CaptureRegionFocus: Component = () => {
+        const { setFocus } = useFocusActions();
+        focusRegion = setFocus;
+        onCleanup(() => {
+            focusRegion = undefined;
+        });
+        return null;
+    };
+
+    // Annotated with the literals rather than `PositionValue`: the values are those
+    // strings, and a handler typed this way stays assignable on an SDK too old to
+    // export the alias.
+    const onEdgeReached = (edge: "top" | "bottom" | "left" | "right"): void => {
+        if (edge === "top") focusRegion?.(navId);
+    };
+
+    // The grid is built by this component's JSX, inside the boundary below — not
+    // above it. A grid created outside the boundary's owner becomes a second root
+    // and never receives a key.
+    return (
+        <FocusBoundary focusId={screenId} initialFocus={gridId} navigation="vertical">
+            <CaptureRegionFocus />
+
+            <FocusBoundary focusId={navId} initialFocus={firstTabId} navigation="horizontal">
+                <NavTab label="Home" focusId={firstTabId} x={0} />
+                <NavTab label="Movies" x={220} />
+            </FocusBoundary>
+
+            <Shelf
+                focusId={gridId}
+                numRows={30}
+                numCols={6}
+                cellSize={[280, 158]}
+                cellSpacing={[24, 32]}
+                translation={[80, 240]}
+                focus={{
+                    horizontal: { strategy: fixedFocusStrategy, options: { focusOffset: 80 } },
+                    vertical: { strategy: floatingFocusYStrategy, options: { focusOffset: 0 } }
+                }}
+                getCellComponent={cardCellComponent}
+                onEdgeReached={onEdgeReached}
+            />
+        </FocusBoundary>
+    );
+};
+```
+
+## Focusable cells (`setFocusBoundary`)
+
+A composite cell — several buttons, a nested grid, real internal navigation — can hand the grid
+its own `FocusBoundary` identity instead of intercepting keys with a `KeyDelegate`. While that
+cell is focused, the grid parks its boundary's virtual focus there, so keys arrive through the
+focus chain and grid navigation runs only when the cell **declines**.
+
+`setFocusBoundary` is a 3.x addition later than 3.0.0, so an install predating it types
+`CellRenderProps` without the prop and the sample below does not compile there. Where
+`props.setFocusBoundary` is missing, `setKeyDelegate` is the composite-cell mechanism every version
+has, with the key order inverted: the delegate runs *before* grid navigation and hands a key back by
+returning `false`, and `isFocused()` does not work inside the cell because no boundary of its own is
+focused.
+
+```tsx rsg-skill=complete
+import { Group, Label, Rectangle } from "@roku-sdk/components";
+import type { CellRenderProps } from "@roku-sdk/flex-grid";
+import { FocusBoundary } from "@roku-sdk/navigation";
+import type { Component } from "@roku-sdk/solid";
+
+interface ShelfItem {
+    title: string;
+}
+
+export const CompositeCell: Component<CellRenderProps<ShelfItem>> = props => {
+    const cellRef: object = {};
+    props.setFocusBoundary(cellRef);
+
+    return (
+        <FocusBoundary focusId={cellRef} initialFocus={cellRef} rememberLastFocus={false}>
+            <group>
+                <rectangle
+                    width={props.width}
+                    height={props.height}
+                    color={props.focused() ? "0x0055FFFF" : "0x1A1A1AFF"}
+                />
+                <label text={props.item?.title ?? "…"} translation={[16, 120]} />
+            </group>
+        </FocusBoundary>
+    );
+};
+```
+
+Requires the outer grid to be in boundary mode (`focusId` set). The registration is **not**
+cleared on pool recycle — drive per-item state from `props.item` and prefer
+`rememberLastFocus={false}`. `rememberLastFocus` remembers per pool node, not per item, so a
+recycled node reopens on whatever the previous item last focused; to remember per item, store
+the last sub-focus on the item and derive `initialFocus` from it. Shared pools support this pattern: when a grid focuses a node,
+a focus relay moves the cell's registration to that grid. All grids sharing the pool
+must be under the same root `FocusBoundary`.
+
+## Nested grids — boundary mode (preferred)
+
+Give the inner grid a `focusId` too, register that identity in the parent cell's
+`FocusBoundary` (`navigationMap` moves sub-focus into it), and set
+`declineUnhandledNavigation: true` so keys the inner grid could not act on keep bubbling.
+Without it the inner boundary claims every movement key and the user is trapped at its edges.
+
+`declineUnhandledNavigation` is the same vintage as `setFocusBoundary` — a 3.x addition later than
+3.0.0 — so an install predating it rejects the config key, and a nested grid there cannot decline a
+movement key it could not act on.
+
+```tsx rsg-skill=complete
+import { Group } from "@roku-sdk/components";
+import type { CellRenderProps } from "@roku-sdk/flex-grid";
+import { createFlexGrid, fixedFocusStrategy, floatingFocusYStrategy } from "@roku-sdk/flex-grid";
+import { FocusBoundary } from "@roku-sdk/navigation";
+import type { Component } from "@roku-sdk/solid";
+
+interface Episode {
+    title: string;
+}
+
+interface Series {
+    episodes: Episode[];
+}
+
+const nestedGridId: object = {};
+const detailZoneId: object = {};
+
+export const SeriesCell: Component<CellRenderProps<Series>> = props => {
+    const cellRef: object = {};
+    props.setFocusBoundary(cellRef);
+
+    const inner = createFlexGrid<Episode>({
+        focusId: nestedGridId,
+        declineUnhandledNavigation: true,
+        numRows: 1,
+        numCols: 12,
+        cellSize: [220, 124],
+        focus: {
+            horizontal: { strategy: fixedFocusStrategy, options: { focusOffset: 40 } },
+            vertical: { strategy: floatingFocusYStrategy, options: { focusOffset: 0 } }
+        },
+        getCellComponent: () => EpisodeCell,
+        onItemSelected: (_row, _col, item) => item !== undefined
+    });
+
+    const navigationMap = new Map<object, Partial<Record<"up" | "down" | "left" | "right", object>>>([
+        [detailZoneId, { right: nestedGridId }],
+        [nestedGridId, { left: detailZoneId }]
+    ]);
+
+    return (
+        <FocusBoundary
+            focusId={cellRef}
+            initialFocus={detailZoneId}
+            rememberLastFocus={false}
+            navigationMap={navigationMap}
+        >
+            <group>{inner.element}</group>
+        </FocusBoundary>
+    );
+};
+
+const EpisodeCell: Component<CellRenderProps<Episode>> = () => <group />;
+```
+
+Escapes are declarative: a `navigationMap` entry on the cell catches a direction (e.g. `left`
+back to a Detail zone), and a direction the cell has no entry for is declined so the outer grid
+changes row.
+
+## Bare: a grid inside another grid's cell
+
+The inner grid gets no `focusId`. The outer cell registers a `KeyDelegate` while it is focused
+and forwards keys into the inner grid, using the return value to decide whether the outer grid
+should act instead.
+
+Forward **both** press and release. A release is what clears a hold timer and settles a smooth
+scroll, so swallowing it leaves the inner grid gliding after the user let go.
+
+```tsx rsg-skill=complete
+import { Group, Label, Rectangle } from "@roku-sdk/components";
+import type { CellRenderProps, KeyDelegate } from "@roku-sdk/flex-grid";
+import { createFlexGrid, fixedFocusStrategy, floatingFocusYStrategy } from "@roku-sdk/flex-grid";
+import { type Component, createEffect, onCleanup } from "@roku-sdk/solid";
+
+interface Episode {
+    title: string;
+}
+
+interface Series {
+    episodes: Episode[];
+}
+
+const EpisodeCell: Component<CellRenderProps<Episode>> = props => (
+    <group>
+        <rectangle
+            width={props.width}
+            height={props.height}
+            color={props.focused() ? "0x0055FFFF" : "0x1A1A1AFF"}
+        />
+        <label text={props.item?.title ?? "…"} translation={[12, 96]} />
+    </group>
+);
+
+function episodeCellComponent(): Component<CellRenderProps<Episode>> {
+    return EpisodeCell;
+}
+
+/** A cell of the outer grid that expands into an inner grid of episodes. */
+export const SeriesCell: Component<CellRenderProps<Series>> = props => {
+    // No focusId: this grid has no boundary and is driven entirely by the
+    // delegate below.
+    const inner = createFlexGrid<Episode>({
+        numRows: 1,
+        numCols: 12,
+        cellSize: [220, 124],
+        cellSpacing: [12, 0],
+        focus: {
+            horizontal: { strategy: fixedFocusStrategy, options: { focusOffset: 40 } },
+            vertical: { strategy: floatingFocusYStrategy, options: { focusOffset: 0 } }
+        },
+        getCellComponent: episodeCellComponent,
+        onItemSelected: (row, col, item) => item !== undefined
+    });
+
+    createEffect(() => {
+        if (!props.focused()) {
+            props.setKeyDelegate(null);
+            return;
+        }
+
+        const delegate: KeyDelegate = {
+            handleKey(key, press) {
+                // false means the inner grid did nothing with it, so the outer
+                // grid gets its turn — that is how an edge escapes the inner row.
+                return inner.forwardKeyEvent(key, press);
+            }
+        };
+
+        props.setKeyDelegate(delegate);
+        onCleanup(() => props.setKeyDelegate(null));
+    });
+
+    return <group>{inner.element}</group>;
+};
+```
+
+### What `forwardKeyEvent` returns
+
+The boolean is the whole contract: `true` means the inner grid consumed the key and the parent
+must not act on it.
+
+| Returns `true` | Returns `false` |
+|---|---|
+| The focused inner cell's own `KeyDelegate` consumed it | A directional press at a non-wrapping edge that moved nothing |
+| A directional press moved focus, or wrapped under a wrap strategy | An idle horizontal release with no hold timer or smooth scroll to settle |
+| A directional press or re-press that a live smooth-scroll session consumed | `OK` when `onItemSelected` is absent or returned `false` — deliberate, so selection bubbles |
+| A directional release that did real work: cleared a hold timer, settled a scroll | A key the grid does not act on at all, such as a `play` release |
+| `OK` accepted by an `onItemSelected` that returned `true` | A key listed in `handleAdditionalKeyEvents` that the focused cell declined |
+
+Two asymmetries worth knowing, because both are silent:
+
+- **Bare mode has no claimed-key filter.** In top-level mode only the boundary's keys reach a
+  cell's delegate; here *every* key you forward is offered to the focused inner cell first,
+  including keys with no navigation meaning. Forwarding a key the inner grid cannot use is
+  harmless, and forwarding only the arrows is what makes an inner cell's `play` handler dead.
+- **`onEdgeReached` fires in both modes**, so an inner grid can report its own edges. Use it
+  when the reaction belongs to the grid; use the `false` return when the reaction belongs to the
+  parent cell, which is the usual case.

package/skills/flex-grid/references/plugins.md

@@ -0,0 +1,201 @@
+# Plugins
+
+Everything optional about a grid is a plugin, and every plugin lives on its own subpath. That is
+deliberate: the main barrel does not re-export them, so a grid without a row title never carries
+the row-title code. Import the factory from the subpath, call it, and pass the result in
+`plugins`.
+
+| Subpath | Factory | What it owns |
+|---|---|---|
+| `@roku-sdk/flex-grid/focus-highlight` | `createFocusHighlightPlugin` | The highlight node around the focused cell, its tweens, layer and visibility |
+| `@roku-sdk/flex-grid/zoom-focus` | `withZoomFocus`, `ScaleTween` | Scale-on-focus on cell templates (not a `plugins[]` entry) |
+| `@roku-sdk/flex-grid/row-titles` | `createRowTitlePlugin` | A title drawn per row, scrolling with it |
+| `@roku-sdk/flex-grid/bob-in-the-middle` | `createBobPlugin` | An interstitial band between two rows |
+| `@roku-sdk/flex-grid/empty-placeholder` | `createEmptyPlaceholderPlugin` | What a cell shows while its row has not loaded |
+| `@roku-sdk/flex-grid/row-clip` | `createRowCardsClipPlugin` | A rect one row's cards scroll through and are cut at |
+| `@roku-sdk/flex-grid/row-backdrop` | `createRowBackdropPlugin` | One backdrop behind a run of rows, under every card |
+| `@roku-sdk/flex-grid/perf` | `createPerfPlugin` | Frame and transaction counters, for a measurement session |
+
+`@roku-sdk/flex-grid/compose-h-strategy` is on the same principle but is not a plugin: it
+composes a horizontal focus *strategy* out of extensions, and its result goes in
+`focus.horizontal.strategy`.
+
+**One import trap.** Two different types are called `FocusHighlightConfig`. The main barrel
+exports a legacy one that nothing reads; the plugin's own is on its subpath. Import the config
+type from `@roku-sdk/flex-grid/focus-highlight` alongside the factory, or the fields you pass
+will be rejected against a shape that has nothing to do with the plugin.
+
+## The focus highlight
+
+| Field | Meaning |
+|---|---|
+| `render` | Your content instead of the default rectangle. Receives `width`, `height` and `focusedRow` as **accessors** |
+| `layer` | `"front"` (default) draws above the cards, `"back"` below them |
+| `visible` | An accessor. Returning false hides the node **and** clears every cell's `focused` signal, which is what dims in-cell outlines while a tab bar or a dialog owns focus |
+| `hideOnSmoothScroll` | Fade the highlight out while a held scroll glides, and back in when it settles |
+| `color` | The default rectangle's colour. Ignored once `render` is set |
+
+`render` runs **once**, untracked, with no Solid parent context — it is a factory, not a
+component body. So read its accessors inside the JSX it returns, and never destructure the
+context object: doing either captures the first focused cell's size and keeps it forever.
+
+```tsx rsg-skill=complete
+import { Poster } from "@roku-sdk/components";
+import type { GridPlugin } from "@roku-sdk/flex-grid";
+import { createFocusHighlightPlugin } from "@roku-sdk/flex-grid/focus-highlight";
+import type { Accessor } from "@roku-sdk/solid";
+
+interface Card {
+    title: string;
+}
+
+const BORDER = 12;
+
+/**
+ * `width` and `height` stay accessors all the way into the JSX props, so the
+ * frame resizes when focus moves to a row with a different cell size.
+ */
+export function cardFocusFrame(uri: string): GridPlugin<Card> {
+    return createFocusHighlightPlugin<Card>({
+        layer: "back",
+        hideOnSmoothScroll: true,
+        render: (ctx: { width: Accessor<number>; height: Accessor<number>; focusedRow: Accessor<number> }) => (
+            <poster
+                uri={uri}
+                width={ctx.width() + BORDER * 2}
+                height={ctx.height() + BORDER * 2}
+                translation={[-BORDER, -BORDER]}
+            />
+        )
+    });
+}
+```
+
+## Scale-on-focus with `withZoomFocus`
+
+Scale-on-focus is a **template** concern, not a plugin. Wrap cell templates at module scope
+with `withZoomFocus` from `@roku-sdk/flex-grid/zoom-focus` so only templates that need zoom
+pull in `ScaleTween`.
+
+`withZoomFocus` arrived in **3.0.0**, which removed the `createZoomFocusPlugin` entry along
+with the `getItemScale` and `requiredNodeSignals` hooks a scale plugin needed. On a 2.x
+install (`@roku-sdk/flex-grid@maintenance-2x`) neither the wrapper nor its subpath export
+exists, so zoom is still a `plugins[]` entry there; see that install's
+`BREAKING_CHANGES.md` for the plugin-to-wrapper migration table.
+
+When templates own the focus visual (zoom scale, in-cell outline), still add
+`createFocusHighlightPlugin` to `plugins` with `renderNode: false` — also **3.0.0**, and the
+half of the zoom migration that is easy to miss. It gates per-cell `focused` — returning
+`false` from `visible` clears every cell's focus styling while a tab bar or dialog owns focus.
+Dropping the highlight plugin because zoom draws the visual is how `visible` stops working.
+
+```tsx rsg-skill=complete
+import type { Component } from "@roku-sdk/solid";
+import type { CellRenderProps, GridPlugin } from "@roku-sdk/flex-grid";
+import { createFocusHighlightPlugin } from "@roku-sdk/flex-grid/focus-highlight";
+import { withZoomFocus } from "@roku-sdk/flex-grid/zoom-focus";
+import type { Accessor } from "@roku-sdk/solid";
+
+interface Card {
+    title: string;
+}
+
+const PortraitCell: Component<CellRenderProps<Card>> = (props) => (
+    <label text={props.item?.title ?? ""} width={props.width} />
+);
+
+const ZoomedPortraitCell = withZoomFocus(PortraitCell, {
+    focusedScale: 1,
+    unfocusedScale: 0.88,
+    durationSec: 0.2
+});
+
+/**
+ * @param gridHasFocus false while a tab bar or dialog owns focus, which drops
+ *   every cell's focused styling via the highlight plugin's `visible`.
+ */
+export function zoomedShelfPlugins(gridHasFocus: Accessor<boolean>): GridPlugin<Card>[] {
+    return [
+        createFocusHighlightPlugin<Card>({ visible: gridHasFocus, renderNode: false })
+    ];
+}
+
+export { ZoomedPortraitCell };
+```
+
+## A backdrop behind several rows
+
+An image or colour behind a run of rows — a brand band under a pill row and a shelf — is
+`createRowBackdropPlugin`, not row chrome. Chrome belongs to one row; this draws each region as
+one node behind every row of the grid, which scrolls with the rows and glides with them when a
+gap such as the bob opens above or inside it. Cards scroll over it horizontally.
+
+| Field | Meaning |
+|---|---|
+| `regions` | An accessor returning `{ rows: [first, last], left?, width?, …your fields }[]`. `rows` is inclusive and is the region's **identity**: keep the tuple and the node stays; your other fields reach `render` as updates |
+| `render` | `(region, size)` — runs **once per mount**, y = 0 at the region top. Read `region()` inside the JSX for anything that changes |
+| `size.fill` | Pass as `ref` to each node spanning the whole region. The plugin owns its `id`, `width` and `height` and glides the height with the rows. The node must live as long as the region, so never put one under `<Show>` |
+| `size.width`, `size.height` | Accessors. `height` is where the rows are heading, not tweened — place content that must not stretch against it |
+| `above` / `below` | Px past the first row's cards and the last row's. `above` defaults to the grid's title reserve, so the band covers the first row's title; `below` to 0 |
+| `left` / `width` | Default to the grid's viewport. In the coordinates the grid's `translation` uses, so `left: 0` with the screen width is full bleed on an inset grid |
+
+A gap opening **inside** the region stretches it, so a `Poster` fill needs
+`loadDisplayMode="scaleToZoom"` or the art distorts. A region more than about two viewports from
+focus is unmounted and re-rendered on return, which reloads its images: bound them with
+`loadWidth` / `loadHeight`, and set `uri` last so cached art does not draw before those apply.
+`createPerfPlugin` reports each mount's nodes as "createElement called after warmup"; that is this
+lifetime, not a leak.
+
+`createRowBackdropPlugin` is a 3.x addition later than 3.0.0, so an install predating it has no
+`@roku-sdk/flex-grid/row-backdrop` entry and the sample below does not compile there.
+
+```tsx rsg-skill=complete
+import type { GridPlugin } from "@roku-sdk/flex-grid";
+import { createFocusHighlightPlugin } from "@roku-sdk/flex-grid/focus-highlight";
+import { createRowBackdropPlugin } from "@roku-sdk/flex-grid/row-backdrop";
+import type { Accessor } from "@roku-sdk/solid";
+
+interface Card {
+    title: string;
+}
+
+interface Brand {
+    name: string;
+    artUri: string;
+}
+
+const SCREEN_WIDTH = 1920;
+const BAND_HEIGHT = 725;
+
+/**
+ * The selected brand's art across the whole screen behind rows 7 and 8. A new
+ * brand updates the poster and label in place; the `rows` tuple never changes.
+ */
+export function brandBandPlugins(brand: Accessor<Brand>): GridPlugin<Card>[] {
+    return [
+        // First: a back-layer highlight listed before it would draw under the band.
+        createRowBackdropPlugin({
+            regions: () => [{ rows: [7, 8] as const, left: 0, width: SCREEN_WIDTH, brand: brand() }],
+            render: (region, size) => (
+                <group>
+                    <poster
+                        ref={size.fill}
+                        loadWidth={SCREEN_WIDTH}
+                        loadHeight={BAND_HEIGHT}
+                        loadDisplayMode="scaleToZoom"
+                        uri={region().brand.artUri}
+                    />
+                    <label text={region().brand.name} translation={[108, 284]} />
+                </group>
+            )
+        }),
+        createFocusHighlightPlugin<Card>({ layer: "back" })
+    ];
+}
+```
+
+## Cost of a plugin array
+
+`plugins` is a structural prop, so a fresh array on every parent render remounts the grid and
+drops focus. Build it once — a module-level constant, a `createMemo`, or a function called once
+like the two above — and never inline the factory calls into JSX.