@roku-sdk/ai 0.0.0-stage → 2.19.0

package/skills/slideshow/SKILL.md

@@ -0,0 +1,157 @@
+# Slideshow
+
+## Overview
+
+`@roku-sdk/slideshow` shows **one thing at a time** and animates between them — a hero banner, a
+full-screen image carousel, an onboarding or promo pager. You give it a slide count, a slide size
+and a `renderSlide` callback; it owns the tween, which slide is current, and the arrows and dots
+drawn around the strip. Three factories render the same handle in three different ways, and they
+differ most in how focus works, not in what they draw.
+
+## Read the reference first for these tasks
+
+| If the request is | Read now, before answering |
+|---|---|
+| Making a slide focusable, or a slide with buttons inside it | `references/focus-and-handoff.md` |
+| Moving focus out of the slideshow at the first or last slide, or into it from a sibling region | `references/focus-and-handoff.md` |
+
+The tables below name the callback and stop there. The three modes build focus in three different
+ways, and the wiring each one needs — including which of them moves focus for you and which only
+tells you it is time — is only in the reference. Answer a focus question from the reference and
+quote it; an answer assembled from a table row here will describe the wrong mode.
+
+## When to Use
+
+- one item on screen at a time, with a transition between items
+- a hero banner or promo pager the viewer steps through with left and right
+- a full-screen image carousel
+- an onboarding flow of panels
+- any of the above where the panels themselves contain buttons
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| A row, shelf, poster grid, or any screen showing many items at once | The `flex-grid` skill | It owns rows, columns and cell recycling. This package has no notion of a row — it advances one whole slide at a time |
+| Which node draws the picture, the text or the button inside a slide | The `sdk-components` skill | A slide's contents are ordinary components. This skill owns the strip around them, not what you put in one |
+| Moving between whole screens rather than between panels of one screen | The `screen-navigation` skill | A slideshow is one screen's content; pushing and popping screens is a different mechanism |
+| A row of buttons or a menu you laid out yourself | `FocusBoundary` + `useFocusable` from `@roku-sdk/navigation` | Nothing transitions, so the tween and slide bookkeeping cost more than the screen needs |
+
+## Quick Reference
+
+### Choosing a factory
+
+| Your situation | Use | Import from |
+|---|---|---|
+| A handful of slides, and/or slides containing focusable buttons | `createSlideshow` | `@roku-sdk/slideshow` |
+| Many slides, each cheap to build, and you do not want them all mounted | `createVirtualSlideshow` | `@roku-sdk/slideshow/virtual` |
+| Many slides of a few repeated shapes, where building SceneGraph nodes is the cost | `createPooledSlideshow` | `@roku-sdk/slideshow/pooled` |
+| You would rather write it as JSX than call a factory | `defineSlideshow<T>()` or `Slideshow` | `@roku-sdk/slideshow` |
+
+`defineSlideshow` wraps **eager mode only**. There is no `defineVirtualSlideshow` and no
+`definePooledSlideshow` — for those two, call the factory.
+
+Eager is the only mode whose individual slides can take focus in the ordinary way. Pooled is the
+opposite extreme: its recycled template slides cannot be focused at all.
+
+### Config
+
+| Field | Notes |
+|---|---|
+| `slideCount`, `slideWidth`, `slideHeight` | The three required fields |
+| `items` | `(T \| undefined)[]`; `undefined` is a slide whose data has not arrived |
+| `margin` | Gap **between** slides, default `0`. It is not padding around the strip |
+| `translation` | `[x, y]` of the whole slideshow on screen |
+| `renderSlide` | Optional; receives `index`, `item`, `focused`, `width`, `height`, `slideFocusId`, `goTo` |
+| `initialIndex` | Default `0` |
+| `animation` | `{ durationSec }` default `0.333`, `{ easeFunction }` default `"outCubic"` |
+| `onSlideChange`, `onSelect` | `(index, item)` |
+| `onEdgeReached` | `(edge)` where `edge` is `"first"` or `"last"` → `references/focus-and-handoff.md` |
+| `focusId` | Identity the enclosing boundary's `initialFocus` or `setFocus` names |
+| `chevrons`, `dots` | A component, or `false` to disable |
+| `windowSize` | Virtual only; slides kept alive each side of current, default `1` |
+| `templates`, `getTemplateId`, `poolSize`, `uniqueSlides` | Pooled only; `poolSize` defaults to `3` per template |
+
+`onKeyEvent` also exists, but treat it as legacy: prefer letting keys reach the slideshow through
+the focus chain, and use `onEdgeReached` for hand-off.
+
+### The handle
+
+All three factories return the same shape: `element`, `currentIndex`, `currentItem`,
+`goTo(index, animated?)`, `next()`, `prev()`, `getCurrentIndex()`,
+`updateSlides(startIndex, items)`, `setSlideCount(n)`.
+
+Render it as `{element()}` — always call it.
+
+### Chrome
+
+| Component | Import from | Props |
+|---|---|---|
+| `DefaultChevrons` | `@roku-sdk/slideshow/chrome/chevrons` | `showLeft`, `showRight`, `onLeft?`, `onRight?`, `width`, `height` |
+| `DefaultDotIndicator` | `@roku-sdk/slideshow/chrome/dots` | `slideCount`, `currentIndex`, `width`, `height` |
+
+Pass the component itself — `chevrons: DefaultChevrons` — not an element. The factory binds the
+props. Both are also re-exported from the package root for convenience.
+
+## Example
+
+A five-slide hero banner with chrome, taking focus from the root boundary:
+
+```tsx rsg-skill=complete
+import { FocusBoundary, useFocusable } from "@roku-sdk/navigation";
+import { createSlideshow, DefaultChevrons, DefaultDotIndicator, FocusableSlide } from "@roku-sdk/slideshow";
+import type { Component } from "@roku-sdk/solid";
+
+const COLORS = ["0x1A1A2EFF", "0x0F3460FF", "0x533483FF", "0x2D6A4FFF", "0xE94560FF"];
+
+const HeroBanner: Component = () => {
+    const slideshowId = {};
+
+    const { element } = createSlideshow<undefined>({
+        slideCount: 5,
+        slideWidth: 1720,
+        slideHeight: 940,
+        translation: [100, 40],
+        margin: 200,
+        focusId: slideshowId,
+        chevrons: DefaultChevrons,
+        dots: DefaultDotIndicator,
+        onEdgeReached: (edge: "first" | "last") => console.log(`at the ${edge} slide`),
+        renderSlide: ({ index, focused, width, height, slideFocusId, goTo }) => (
+            <FocusableSlide slideFocusId={slideFocusId} onFocused={goTo}>
+                <rectangle width={width} height={height} color={COLORS[index]} />
+                <label text={`Slide ${index + 1}`} translation={[60, 60]} color="0xFFFFFFFF" />
+                <label text={focused() ? "[ FOCUSED ]" : ""} translation={[60, 130]} color="0x88FF88FF" />
+            </FocusableSlide>
+        ),
+    });
+
+    return (
+        <FocusBoundary focusId={{}} initialFocus={slideshowId}>
+            {element()}
+        </FocusBoundary>
+    );
+};
+
+// `useFocusable` is what FocusableSlide uses internally for a non-interactive slide.
+void useFocusable;
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Slides render, but left and right do nothing and no slide is ever focused | `renderSlide` returns bare nodes, so nothing registers with the boundary | Wrap a non-interactive slide in `FocusableSlide` and hand it `slideFocusId` → `references/focus-and-handoff.md` |
+| Nothing renders at all, or the strip appears only after a key press | `element` was rendered without calling it | It is a thunk: write `{element()}` |
+| At the last slide, `onEdgeReached` fires but focus stays put | In eager and virtual modes the callback only *notifies* — it does not move focus | Call `setFocus` yourself in the callback → `references/focus-and-handoff.md` |
+| A chevron is missing or half off the screen | Chevrons are drawn outside the slide box, roughly 80px beyond each edge | Give the slideshow enough `translation` room on both sides; `margin` will not help, it is the gap between slides |
+| Chevrons or dots never appear | An element was passed instead of a component | Pass `chevrons: DefaultChevrons`, not `chevrons: <DefaultChevrons … />` |
+| A pooled slide's buttons cannot be reached with the remote | Pooled templates render outside the focus context and can never be focused | List that index in `uniqueSlides`, which routes it through `renderSlide` instead of the pool |
+| A virtual slideshow scrolls but focus lags a slide behind | `goTo` was wired into `onFocusGained` as eager mode requires | Virtual mode drives navigation itself — leave `goTo` for programmatic jumps such as an auto-advance timer |
+| `slideRef` is not defined on the render props | It was renamed | It is `slideFocusId` |
+
+## Source of truth
+
+Prefer the typed source over any prose, including this file: read
+`node_modules/@roku-sdk/slideshow/src/types.ts` for the config, the render props and the handle,
+and the factory's own destructure for a default this file does not list.

package/skills/slideshow/references/focus-and-handoff.md

@@ -0,0 +1,187 @@
+# Slideshow focus and hand-off
+
+Everything focus-related imports from `@roku-sdk/navigation`, never from `@roku-sdk/components`.
+
+## The three modes build focus three different ways
+
+This is the fact the body cannot compress, and it decides every answer below.
+
+| Mode | What it renders | How left/right move | At the first or last slide |
+|---|---|---|---|
+| `createSlideshow` (eager) | A `FocusBoundary` with `navigation="horizontal"` | The boundary walks between slide positions | Fires `onEdgeReached`, and **keeps** the key |
+| `createVirtualSlideshow` | A `FocusBoundary` with no `navigation` | The factory calls `prev()` / `next()` and moves focus itself | Fires `onEdgeReached`, and **keeps** the key |
+| `createPooledSlideshow` | **No boundary** — a single leaf `useFocusable` | Its `onKey` handlers advance the index | Declines the key, so focus leaves on its own |
+
+Two consequences worth stating outright:
+
+- **In eager and virtual modes, `onEdgeReached` does not move focus.** It tells you the viewer
+  pushed past the end. Moving focus is your job, with `setFocus` from `useFocusActions()`.
+- **In pooled mode you often need no hand-off code at all.** Its edge handler returns `bubble`, so
+  the key bubbles and the enclosing boundary's `navigationMap` decides where focus goes.
+
+## `slideFocusId`
+
+`renderSlide` receives `slideFocusId: object` — an opaque identity created once per slide
+**position** at factory init, not a node ref and not derived from the item. It stays with the
+position when the data changes, and `setSlideCount` grows the list.
+
+Also on the render props: `goTo()`, already bound to that slide's index, so you call it with no
+arguments.
+
+## A non-interactive slide
+
+A slide that is only a picture and a caption still has to register, or nothing in the slideshow
+is focusable and no key does anything. `FocusableSlide` is the helper for exactly this:
+
+```tsx rsg-skill=complete
+import { createSlideshow, FocusableSlide } from "@roku-sdk/slideshow";
+import type { Component } from "@roku-sdk/solid";
+
+const Banner: Component = () => {
+    const { element } = createSlideshow<undefined>({
+        slideCount: 3,
+        slideWidth: 1720,
+        slideHeight: 940,
+        focusId: {},
+        renderSlide: ({ index, width, height, slideFocusId, goTo }) => (
+            <FocusableSlide slideFocusId={slideFocusId} onFocused={goTo}>
+                <rectangle width={width} height={height} color="0x1A1A2EFF" />
+                <label text={`Panel ${index + 1}`} translation={[60, 60]} color="0xFFFFFFFF" />
+            </FocusableSlide>
+        ),
+    });
+    return <>{element()}</>;
+};
+```
+
+`onFocused={goTo}` is what keeps the strip in sync when focus lands on a slide. In **eager** mode
+wire it. In **virtual** mode you may leave it off — that factory moves focus itself — and `goTo`
+is then only for programmatic jumps such as an auto-advance timer.
+
+## A slide with buttons in it
+
+An interactive slide is a nested boundary, and `slideFocusId` is its `focusId`. Wire each
+button's `onFocusGained` to `goTo` so the strip follows focus into the slide:
+
+```tsx rsg-skill=complete
+import { FocusBoundary, useFocusable } from "@roku-sdk/navigation";
+import { createSlideshow } from "@roku-sdk/slideshow";
+import type { Component } from "@roku-sdk/solid";
+
+const Button: Component<{ label: string; x: number; focusId: object; onFocused: () => void }> = props => {
+    const { isFocused, ref } = useFocusable({
+        focusId: props.focusId,
+        onFocusGained: () => props.onFocused(),
+        onKey: { OK: (press: boolean) => { if (press) console.log(props.label); } },
+    });
+    return (
+        <group ref={ref} translation={[props.x, 0]}>
+            <rectangle width={200} height={70} color={isFocused() ? "0x0066FFFF" : "0x333333FF"} />
+            <label text={props.label} width={200} height={70} horizAlign="center" vertAlign="center" />
+        </group>
+    );
+};
+
+const Pager: Component = () => {
+    const { element } = createSlideshow<undefined>({
+        slideCount: 3,
+        slideWidth: 1720,
+        slideHeight: 940,
+        focusId: {},
+        renderSlide: ({ width, height, slideFocusId, goTo }) => {
+            const btnIds: object[] = [{}, {}];
+            return (
+                <group>
+                    <rectangle width={width} height={height} color="0x0F3460FF" />
+                    <FocusBoundary focusId={slideFocusId} initialFocus={btnIds[0]} navigation="horizontal">
+                        <Button label="Play" x={0} focusId={btnIds[0]} onFocused={goTo} />
+                        <Button label="More" x={220} focusId={btnIds[1]} onFocused={goTo} />
+                    </FocusBoundary>
+                </group>
+            );
+        },
+    });
+    return <>{element()}</>;
+};
+```
+
+Only **eager** mode supports this. Pooled `templates` receive `PooledSlideRenderProps`, which
+carries neither `slideFocusId` nor `goTo` — a pooled template can never be focusable. To make one
+particular pooled slide interactive, name its index in `uniqueSlides`; those bypass the pool and
+go through `renderSlide` with the full render props.
+
+## Taking focus in
+
+Give the slideshow a `focusId` and name it from the enclosing boundary:
+
+```tsx rsg-skill=complete
+import { FocusBoundary } from "@roku-sdk/navigation";
+import { createSlideshow } from "@roku-sdk/slideshow";
+import type { Component } from "@roku-sdk/solid";
+
+const Screen: Component = () => {
+    const slideshowId = {};
+    const { element } = createSlideshow<undefined>({
+        slideCount: 4,
+        slideWidth: 1720,
+        slideHeight: 700,
+        focusId: slideshowId,
+    });
+    return (
+        <FocusBoundary focusId={{}} initialFocus={slideshowId}>
+            {element()}
+        </FocusBoundary>
+    );
+};
+```
+
+When `focusId` is set, the handle's `element()` **must** be rendered inside a `FocusBoundary`.
+
+## Handing focus back out
+
+In eager and virtual modes, do it in `onEdgeReached`. The argument is `"first"` or `"last"` —
+horizontal ends, not `"left"` / `"right"` and not a vertical edge:
+
+```tsx rsg-skill=complete
+import { FocusBoundary, useFocusActions } from "@roku-sdk/navigation";
+import { createSlideshow } from "@roku-sdk/slideshow";
+import type { Component } from "@roku-sdk/solid";
+
+const Screen: Component = () => {
+    const slideshowId = {};
+    const menuId = {};
+
+    const Inner: Component = () => {
+        const { setFocus } = useFocusActions();
+        const { element } = createSlideshow<undefined>({
+            slideCount: 4,
+            slideWidth: 1720,
+            slideHeight: 700,
+            focusId: slideshowId,
+            onEdgeReached: (edge: "first" | "last") => {
+                if (edge === "last") setFocus(menuId);
+            },
+        });
+        return <>{element()}</>;
+    };
+
+    return (
+        <FocusBoundary focusId={{}} initialFocus={slideshowId}>
+            <Inner />
+        </FocusBoundary>
+    );
+};
+```
+
+`useFocusActions()` must be called inside the boundary, which is why the slideshow is built in an
+inner component here rather than beside the boundary that owns it.
+
+For **pooled** mode this is usually unnecessary: its edge handler returns `bubble`, the key bubbles
+to the enclosing boundary, and a `navigationMap` entry there moves focus. Add `onEdgeReached` only
+when you need to run something else at the edge as well.
+
+## Things that do not exist
+
+`slideRef` was renamed to `slideFocusId`, and the config field `focusRef` to `focusId`. There is
+no `navigationMap` on a slideshow config, no per-slide `nextFocus*` property, and no
+`onSlideExit`. Hand-off is `onEdgeReached` plus `setFocus`, or bubbling in pooled mode.

package/skills/solid-on-roku/SKILL.md

@@ -0,0 +1,181 @@
+# Solid on Roku
+
+## Overview
+
+An RSG SDK TypeScript app is a SolidJS app whose reactivity is unchanged and whose
+*surroundings* are not: primitives that need a browser scheduler are not re-exported, the engine
+running the code hoists `let` like `var`, a development build swaps three primitives for
+instrumented ones, and the anchor node hands the app its input fields as signal getters rather
+than as a plain object. This skill is the seam — what the platform does differently from what the
+SolidJS documentation describes.
+
+## When to Use
+
+Use this when Solid code is correct by the framework's rules and the platform disagrees:
+
+- an import from `@roku-sdk/solid` that does not resolve, for a primitive `solid-js` documents
+- an anchor node input field read once that never changes again, or an effect that re-runs on
+  fields it never named
+- a `let` or `const` inside a loop behaving as if it were `var`
+- a generator function the app cannot use
+- a signal that behaves one way under a development build and another under a shipped one
+- a conditional element with no fallback, and whether SceneGraph's lack of text nodes makes that
+  unsafe
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Handling or recovering from something that threw | The `logging-and-errors` skill | This skill owns which primitives exist, not what to do when one of them throws |
+| An assertion reading stale state in a test | The `testing` skill | When effects flush under a test harness is a testing concern, not a platform one |
+| Which node draws a thing, or what to pass it | The `sdk-components` skill | Reactivity is the same question everywhere; the component surface is its own |
+| Which item is focused, or what a key press does | The `focus-management` skill | Focus is a signal, but which signal and who owns it is that skill's whole subject |
+| Which package a Solid import comes from, and declaring it | The `project-setup` skill | Import every primitive from `@roku-sdk/solid`, never `solid-js` — that rule and the `package.json` it needs live there |
+
+## Read the reference first for two of these tasks
+
+| If the request is | Read now, before answering |
+|---|---|
+| The build rejected a module, or a transform did something to it that has to be explained | `references/hermes-and-exports.md` |
+| Whether a specific `solid-js` symbol exists here, beyond the ones named below | `references/hermes-and-exports.md` — the full excluded table, with a reason per row |
+
+The tables below name every fact; the reference carries the shapes and the complete lists. An
+answer that needs one exact symbol should not open the file.
+
+## Quick Reference
+
+| Question | Answer |
+|---|---|
+| Where do primitives come from | `@roku-sdk/solid`, always |
+| What is missing, and why | `createDeferred` (needs `MessageChannel`), `lazy` (needs dynamic `import()`), `SuspenseList` and `enableScheduling` (need the concurrent scheduler), `enableHydration` (SSR), `onError` (deprecated upstream), plus thirteen `solid-js` internals |
+| Reading an anchor node input | Name the field inside a reactive scope: `createMemo(() => inputs.title)` |
+| Why a top-level read of `inputs` never updates | The component function is invoked inside `untrack`, so nothing read while it runs subscribes |
+| Why an effect re-runs on fields it never named | Every field is an **enumerable** getter, so spreading, `Object.keys` + read, or stringifying `inputs` subscribes to all of them |
+| Why `inputs.title` is `possibly 'undefined'` | The inputs type is `Partial`, though a declared field always holds its descriptor default at runtime — restate the default: `inputs.title ?? "Loading"` |
+| `let` in a loop | Hermes hoists it to function scope; the SDK's block-scoping transform restores per-iteration capture |
+| Generator functions | Not usable — Hermes does not support them, so no transform covers them |
+| What a development build changes | `createSignal`, `createMemo` and `createEffect` are instrumented wrappers, and `__DEV__` is set |
+| A conditional with no fallback | Safe. Between siblings the renderer's `createTextNode("")` returns an empty `group` to hold the position; as a sole child there is no node at all |
+| Reading a prop | Inside JSX, `createMemo`, `createEffect` or a callback — never destructured, never once at the top |
+
+## Instructions
+
+1. **Import every primitive from `@roku-sdk/solid`.** It re-exports the part of `solid-js` that
+   works under the SceneGraph renderer, plus the SDK's own symbols. `project-setup` owns the
+   dependency rule; what matters here is that a primitive absent from this package is absent on
+   purpose, and the reference gives the reason for each one.
+
+2. **Do not reach for a missing primitive's `solid-js` original.** Installing `solid-js` beside
+   the SDK gives you a second reactive graph, not the missing feature — and the feature is missing
+   because the runtime cannot carry it. For a deferred value, throttle the *source* signal
+   yourself, with the SDK's own timing helpers; for code splitting, there is none to do, since the
+   module system is static. Do not substitute a browser scheduling or frame-timing API either —
+   this is not a browser, and none of them exist here.
+
+3. **Read anchor node inputs by naming one field, inside a reactive scope.** Each input field is
+   an enumerable getter over its own signal, so `inputs.title` inside a `createMemo` subscribes to
+   `title` alone. Two consequences follow, and they pull in opposite directions:
+   - A read at the top of the component body subscribes to **nothing** — the body is invoked
+     inside `untrack` — so the value is whatever it was at construction, forever.
+   - A read that touches the object *as a whole* inside a tracking scope subscribes to
+     **everything**. Spreading it, iterating its keys, or putting it in a log line does this.
+
+   The inputs type is `Partial`, so every field reads as possibly `undefined` even though a
+   declared field always holds its descriptor default. Restate that default at the read —
+   `inputs.title ?? "Loading"` — rather than asserting non-null.
+
+4. **Never destructure `props`, and never read `props.x` once at the top of a component.** The
+   compiler passes a component's props as an object of memoized getters, so a read is a call and
+   destructuring calls each one immediately and keeps the value. Read inside JSX, `createMemo`,
+   `createEffect` or a callback. `splitProps` and `mergeProps` are the sanctioned exceptions.
+
+5. **Write loops as you would anywhere, and know why they work.** Hermes hoists `let` and `const`
+   to function scope, which would make every closure created in a loop share one variable. The
+   SDK's block-scoping transform runs after `babel-preset-solid` and restores per-iteration
+   capture, so the ordinary shape is correct. Do not hand-write an immediately invoked wrapper to
+   "fix" it.
+
+6. **Do not use generator functions.** Hermes does not support them at all, so this is a language
+   limit rather than a transform gap — and it is why the block-scoping transform does not handle
+   `yield` inside a loop. Return an array, or expose a `next()` closure over an index.
+
+7. **Assume a development build is not the build you ship.** It sets `__DEV__` and replaces
+   `createSignal`, `createMemo` and `createEffect` with instrumented wrappers that record reactive
+   activity. Behaviour matches, but timing and anything you measure through them do not — so never
+   conclude a performance question from a development build, and never leave code that depends on
+   the wrappers being there.
+
+8. **Leave `fallback` off a conditional when there is nothing to show.** SceneGraph has no text
+   nodes, so the universal renderer's `createTextNode("")` is answered with an empty `group`
+   instead — childless, zero-size, and silent, because the renderer only warns for non-empty
+   text. One is created to hold the position when a conditional between siblings renders
+   nothing. Supplying a fallback purely to avoid it buys nothing.
+
+## Example
+
+An anchor node whose two input fields are written by the host while the app runs. It reads each
+field by name inside a reactive scope, so each subscription is to one field.
+
+```tsx rsg-skill=complete
+import { Label, LayoutGroup, Rectangle } from "@roku-sdk/components";
+import { type AnchorNodeImplementation, defineAnchorNode, FieldType } from "@roku-sdk/rsg-ts";
+import { createEffect, createMemo, Show } from "@roku-sdk/solid";
+
+const ProgressPanelDescription = {
+    componentName: "ProgressPanel",
+    extends: "Group" as const,
+    inputFields: {
+        title: FieldType.String("Loading"),
+        progress: FieldType.Float(0)
+    },
+    outputFields: {
+        settled: FieldType.Boolean()
+    }
+};
+
+const ProgressPanel: AnchorNodeImplementation<typeof ProgressPanelDescription> = (inputs, outputs) => {
+    // Naming one field subscribes to that field alone. Reading `inputs` as a whole
+    // here — spreading it, or putting it in a log line — would subscribe to both.
+    // Every field is typed optional, so restate the descriptor's default.
+    const heading = createMemo(() => (inputs.title ?? "Loading").toUpperCase());
+    const progress = createMemo(() => inputs.progress ?? 0);
+    const barWidth = createMemo(() => Math.round(progress() * 600));
+
+    createEffect(() => {
+        if (progress() >= 1) {
+            outputs.settled(true);
+        }
+    });
+
+    return (
+        <layoutGroup layoutDirection="vert">
+            <label text={heading()} width={600} height={48} color="0xFFFFFFFF" />
+            {/* No fallback: the renderer holds the position with one empty placeholder. */}
+            <Show when={barWidth() > 0}>
+                <rectangle width={barWidth()} height={8} color="0x0055FFFF" />
+            </Show>
+        </layoutGroup>
+    );
+};
+
+export default defineAnchorNode(ProgressPanelDescription, ProgressPanel);
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| An import from `@roku-sdk/solid` does not resolve, though `solid-js` documents the symbol | It is one of the deliberately excluded exports | Read the reference's table for the reason and the alternative; do not install `solid-js` to get it |
+| An anchor node input field holds its startup value forever | It was read at the top of the component body, which runs inside `untrack` | Read it inside `createMemo`, `createEffect` or JSX |
+| An effect re-runs whenever any input field changes | The effect read `inputs` as a whole — a spread, a key iteration, or a log line — and every field is an enumerable getter | Name the one field the effect depends on |
+| A component renders once with the right value and never updates | `props` was destructured, or read once into a local at the top | Read `props.x` inside a reactive scope; use `splitProps` when a subset is genuinely needed |
+| `TS18048: 'inputs.x' is possibly 'undefined'` on a field the descriptor gives a default | The inputs type is `Partial`, so it is wider than the runtime | Restate the descriptor's default at the read — `inputs.x ?? <default>` — rather than `!` |
+| A measurement taken around signals disappears from the shipped build | Those numbers came from the development build's instrumented `createSignal` / `createMemo` / `createEffect` | Measure the build you ship; treat the wrappers as a development aid only |
+| A generator function fails on the device | Hermes has no generator support, and no transform adds it | Return an array, or expose a `next()` closure |
+| A hand-written wrapper was added around a loop body to capture the index | The block-scoping transform already does this, after `babel-preset-solid` | Delete the wrapper and write the ordinary loop |
+| A fallback was added to every conditional to avoid text nodes | `createTextNode("")` yields an empty `group` here, not a text node | Leave `fallback` off unless there is something to show |
+| A node passed by reference, such as `effect={focused() ? <effect …/> : <effect …/>}`, is rebuilt on every change | The prop expression reads the signal itself, so each change builds a new node; a signal read by that node's own fields would update it in place | Hoist each node into a `const` and choose between them — the `effects` skill. This is about node-valued fields, not `fallback` or children, which are inline by design |
+
+The `@roku-sdk/solid` export surface is enumerated in the package's own `EXPORTS.md`, including
+the SDK-specific symbols this skill does not cover. Prefer it over any prose, including this file,
+when the two disagree.

package/skills/solid-on-roku/references/hermes-and-exports.md

@@ -0,0 +1,130 @@
+# Hermes and the Export Surface
+
+Two things the SDK does to ordinary Solid code before it runs: it withholds primitives the
+runtime cannot carry, and it rewrites loops the engine would otherwise get wrong. The body names
+every fact here; this file is the complete lists and the shapes.
+
+## The compile pipeline, in order
+
+```
+TypeScript → Babel (babel-preset-solid) → block-scoping transform → Hermes bytecode
+```
+
+Order is the part worth holding on to. The block-scoping transform runs **after** Babel has
+already turned components into reactive calls, so it operates on the emitted code rather than on
+what was written. A closure Babel generated is treated exactly like one authored by hand.
+
+## Why the loop transform exists
+
+Hermes does not implement block scoping. `let` and `const` are hoisted to function scope and
+behave as `var`, so every closure created in a loop would capture the same binding and observe
+the final value.
+
+```ts
+// Authored — correct everywhere block scoping is real
+for (let i = 0; i < 5; i += 1) {
+    schedule(() => report(i));
+}
+// Without the transform, on Hermes: five closures, all reporting 5.
+```
+
+The transform restores per-iteration capture, so the ordinary shape is the correct one. Two
+things follow:
+
+- **Do not hand-write a wrapper** — an immediately invoked function around the loop body, or a
+  `.forEach` used purely to get a fresh binding. It is redundant, and it hides the intent.
+- **The fix is compile-time.** Code that never goes through the SDK's build — a snippet evaluated
+  some other way — does not get it.
+
+This is a workaround with an expiry: Hermes is gaining native block scoping, and the transform is
+documented as removable once that lands. Treat the shape as permanent and the mechanism as not.
+
+## Generator functions
+
+Hermes does not support `function*` at all. This is not a gap in the transform — there is nothing
+for it to transform into, which is why the transform explicitly does not handle `yield` inside a
+loop.
+
+```ts
+// Not usable on the device
+function* pages(): Generator<number> {
+    for (let i = 0; i < 5; i += 1) {
+        yield i;
+    }
+}
+```
+
+Replace with whichever fits:
+
+- return the whole array when it is small enough to build eagerly;
+- expose a closure over an index — `const next = () => items[cursor++]` — when it is not;
+- use a signal for the cursor when the consumer is reactive.
+
+## Excluded exports, with the reason for each
+
+These exist in `solid-js` or `solid-js/store` and are **not** re-exported by `@roku-sdk/solid`.
+Reaching past the package for one does not work: the reason is the runtime, not the packaging.
+
+### Withheld because the platform cannot carry them
+
+| Export | Reason | What to do instead |
+|---|---|---|
+| `createDeferred` | Solid's scheduler needs `MessageChannel`, which the Roku Hermes runtime does not have — the import fails with `ReferenceError: Property 'MessageChannel' doesn't exist` | Throttle the source signal, or derive from a signal you update on your own cadence |
+| `lazy` | Dynamic `import()` against a static module system | Import statically; there is no split bundle to defer |
+| `SuspenseList` | Coordinates several `<Suspense>` boundaries through the concurrent scheduler | Order the loading states yourself with ordinary signals |
+| `enableScheduling` | Platform-specific scheduler wiring that has no Roku implementation | Nothing to enable |
+| `enableHydration` | Server-side rendering, which does not apply here | Nothing to hydrate |
+| `enableExternalSource` | A hook for bridging external reactive libraries; no current demand | Adapt the external source into a signal by hand |
+| `onError` | Deprecated upstream | `catchError` — and for containing a throw at all, the `logging-and-errors` skill |
+
+### Withheld as internals
+
+Not part of the public API in `solid-js` either. If one of these looks necessary, the design
+usually wants revisiting rather than the symbol.
+
+| Export | Source |
+|---|---|
+| `equalFn` | `solid-js` |
+| `getListener` | `solid-js` |
+| `requestCallback` | `solid-js` |
+| `cancelCallback` | `solid-js` |
+| `sharedConfig` | `solid-js` |
+| `createComponent` | `solid-js` |
+| `$PROXY`, `$TRACK`, `$DEVCOMP` | `solid-js` |
+| `isWrappable` | `solid-js/store` |
+| `setProperty` | `solid-js/store` |
+| `updatePath` | `solid-js/store` |
+| `$RAW` | `solid-js/store` |
+
+## What a development build substitutes
+
+A development build sets `__DEV__`, and re-exports `createSignal`, `createMemo` and
+`createEffect` from an instrumented module rather than from the reactive core. The wrappers record
+reactive activity for tooling; semantics match, timing does not.
+
+The consequences worth acting on:
+
+- **Never measure performance on it.** Every signal read and write carries bookkeeping the
+  shipped build does not.
+- **Never depend on the instrumentation existing.** Code that reads what the wrappers record
+  compiles fine and does nothing in the build you ship.
+- **A behavioural difference between the two builds is worth reporting**, since the wrappers are
+  meant to be transparent.
+
+## The placeholder node behind a fallback-less conditional
+
+SceneGraph has no text nodes, but the universal renderer asks for one to hold a position. The
+SDK's renderer answers that by creating an empty `group`: childless, zero-size, no layout effect.
+The warning path is only for *non-empty* text, so a positional placeholder is silent.
+
+It appears in one situation: a conditional with no `fallback`, rendering falsy, as a direct child
+of a real element **with siblings** — the compiler needs a marker to know where the content goes
+when it comes back. Inside a fragment there is no marker and no placeholder, because a fragment
+compiles to an array.
+
+Each placeholder is its own node, and that is deliberate — the renderer tracks children by object
+identity and a node has one parent, so a shared placeholder would corrupt positional tracking for
+every conditional after the first. The cost is one node creation and one append, against the
+hundreds a screen makes for real content.
+
+So: leave `fallback` off when there is nothing to show. Add one when there is.