@roku-sdk/ai 0.0.0-stage → 2.19.0

package/skills/fonts-and-glyphs/SKILL.md

@@ -0,0 +1,231 @@
+# Fonts and Glyphs
+
+## Overview
+
+Two questions decide whether text in an RSG SDK app renders the way you meant: which typeface is
+supplying the characters, and whether that typeface actually has them. Get the first wrong and
+text comes out at a size nobody can read, or ignores the size you set. Get the second wrong and
+you ship empty boxes — and the boxes appear on a device you did not test, because the firmware's
+fallback font hides the problem everywhere else.
+
+## When to Use
+
+- text rendering as empty boxes, on any device or only on some, and whether `fallbackGlyph` helps
+- symbols that were fine until the app started shipping a typeface of its own
+- a symbol needed in a label — arrow, chevron, star, check mark, remote-button icon
+- text that renders far too small, or ignores the size you set
+- shipping a `.ttf` or `.otf` with the app, and a build that refuses two of them
+- deciding whether a shape should be a character at all
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Which node draws the text — `Label`, `SimpleLabel`, `ScrollingLabel`, `MultiStyleLabel` | The `sdk-components` skill | This skill owns the typeface, that one owns the node |
+| Brand marks, multi-colour or gradient artwork | The `sdk-components` skill | That is a `Poster` and an image, not a character |
+| Where an asset file belongs in the project before anything can import it | The `project-setup` skill | Project layout is that skill's job |
+
+## Read the reference first for this task
+
+| If the request is | Read now, before answering |
+|---|---|
+| Naming a specific glyph constant, or auditing which ones survive a custom font | `references/glyph-tables.md` |
+
+The body tells you which *group* a symbol falls in and what that means. The 45 constants, their
+codepoints and their three groups are only in the reference. Guessing a constant name is the one
+mistake here that compiles.
+
+## Quick Reference
+
+| Job | Reach for |
+|---|---|
+| Any arrow, chevron, star, tick, or remote-button icon | A named constant from `@roku-sdk/components/glyphs` — never a typed or escaped literal |
+| A character you can simply type (`·`, `°`, currency, quotes, maths) | Type it. These get no constants on purpose |
+| A brand mark or anything multi-colour | Not a character at all — that is `sdk-components` territory |
+| Set a typeface on a `Label` | A `Font` node in the `font` prop, with **both** `uri` and `size` |
+| `Font.size` | Points. **Defaults to 1**, which is why an otherwise correct font renders as a line of dots |
+| Set a typeface on a `SimpleLabel` | `fontUri` plus `fontSize` — no `Font` node |
+| Built-in font names | Ten. The eight `font:…SystemFont` names are **fixed size and ignore `fontSize`**; only `font:SystemFontFile` and `font:BoldSystemFontFile` respect it |
+| Ship a typeface with the app | `import fontUri from "./fonts/whatever.ttf"` — the import resolves to the packaged path at build time |
+| Two font files with the same filename | A build error if their contents differ, reuse if identical. Rename one |
+| Wait until a font can be measured | `whenFontReady(ref)` or `createFontReady(fontRef)` from `@roku-sdk/rsg-ts/runtime` — never a fixed timer |
+| Text arriving from outside with characters your font lacks | Constrain the text or widen the typeface. **`Font.fallbackGlyph` does not substitute anything on current firmware** — see instruction 8 |
+| A `Font` with a `size` and no `uri` | Draws nothing at all. It does not fall back to the system font — omit the `Font` node instead |
+| Which symbols survive a custom app font | The 32 private-use glyphs and `●` `★` `☆`. The other ten do not |
+
+## Instructions
+
+1. **Take symbols from the constants, not from your keyboard or an escape.** Import by name from
+   `@roku-sdk/components/glyphs` and interpolate. A literal like `"\uE025"` is the same character
+   today and an unlabelled magic number the moment the font revision moves; the constant for that
+   one is `LEFT_BUTTON_GLYPH`.
+
+2. **Know the one fact that decides whether a symbol renders: which font supplies it.** The
+   constants are grouped by that, not by codepoint:
+   - **RokuFont01 private-use glyphs** (32 of them) — RokuFont01 is the firmware's system-wide
+     fallback font, so these render under a system font *and* under a custom app font.
+   - **Unicode characters that RokuFont01 backs** — `●` `★` `☆`. Same fallback, so also safe.
+   - **RokuUI-Regular symbols** (10 of them — the arrows, dashes, bullet, ellipsis, tick and
+     ballot X). RokuUI-Regular is the default UI font but is **not** in the fallback chain. Under
+     a system font they are fine; under a custom app font they get no backstop and go tofu unless
+     your font happens to supply them.
+
+   So the counter-intuitive part: if your app ships a typeface, the constants that need care are
+   the plain-Unicode-looking ones, not the exotic private-use ones.
+
+3. **Remember that a custom font wins outright where it defines a codepoint.** No fallback occurs.
+   A licensed font carrying its own private-use glyphs at `U+E0xx` will render *those* in place of
+   the Roku icons, which looks like corruption rather than a font choice.
+
+4. **Give a `Font` node a `size`, always.** `Font.size` is in points and defaults to **1**. A
+   `Font` with a correct `uri` and no `size` is the classic "the font loaded but the text is
+   unreadable" report. Set both together and treat them as one prop.
+
+5. **On `SimpleLabel`, use `fontUri` and `fontSize` — and know which built-in names ignore the
+   size.** Of the ten built-in names, eight are fixed-size (`font:Smallest…`, `font:Small…`,
+   `font:Medium…`, `font:Large…`, each plain and `Bold`) and **discard `fontSize` silently**. Only
+   `font:SystemFontFile` and `font:BoldSystemFontFile`, and any font file of your own, respect it.
+   If a size change does nothing, the name is the reason.
+
+6. **Import font files; do not write packaged paths by hand.** `import fontUri from
+   "./fonts/inter.ttf"` gives you a string that is the packaged path, and the build copies the
+   file for you. Both `.ttf` and `.otf` are declared. Writing the path as a literal skips the copy
+   and ships a reference to a file that is not there.
+
+7. **Expect a build error when two font files share a filename.** The build keys them by filename
+   alone, so two files called `Inter.ttf` in different directories collide. Identical contents are
+   silently reused; different contents fail the build with a `Font naming conflict` naming both
+   sources. Rename one — the directory does not disambiguate them.
+
+8. **Do not plan around `fallbackGlyph`.** `Font.fallbackGlyph` reads like the answer to
+   uncontrollable text — a character of your choosing instead of a box — and on current firmware
+   it does not deliver one. Measured on a Roku Native running 16.0.4: set as a bare `u25CF` (the
+   form the SDK's own documentation shows) and as a literal `●`, against both a symbol only the
+   default UI font has and a codepoint no font on the device has, the boxes were unchanged in
+   every combination. The property is real and the SDK does forward it; what is missing is any
+   visible effect. Treat unsupported characters as something to prevent, not something to
+   substitute: constrain the text, or ship a typeface that covers it.
+
+9. **Do not use firmware placeholder syntax for app text.** Translated firmware strings may
+   contain tokens like `{BACK_BUTTON_GLYPH}`. Those are runtime text tokens resolved by the
+   firmware's own string layer, not TypeScript symbols; putting one in a label renders the braces
+   literally. Interpolate the imported constant instead.
+
+10. **Wait for a font with `whenFontReady`, not a timer.** `getFontMeasure()` throws
+    `"Font is not yet loaded"` until the GfxFont is published. Current firmware has no Font
+    `loadStatus` field; use `whenFontReady(ref)` (promise) or `createFontReady(fontRef)`
+    (Solid accessor that cancels on cleanup; pass `() => props.uri` or similar as its second
+    argument when the `<font>` node's `uri` or `size` can change) from `@roku-sdk/rsg-ts/runtime`, which keep
+    working when one ships. Do not copy the fixed 100ms / 500ms timer stubs from older
+    examples — those race on a cold cache. A `<font>` that is not on a drawn label is only
+    published if `preUpdate` is set before `uri` and `size`; without it the font never loads
+    and the wait never resolves.
+
+## Measuring a font
+
+`whenFontReady` and `createFontReady` ship in SDK 2.19.0. On 2.18.0 and earlier they are
+not exported from `@roku-sdk/rsg-ts/runtime`.
+
+Capture the Font node's `TmNodeRef` from `ref={node => … node.r}`, then wait before measuring:
+
+```tsx rsg-skill=complete
+import { getFontMeasure, whenFontReady, createFontReady } from "@roku-sdk/rsg-ts/runtime";
+import { createEffect, createSignal, type Component } from "@roku-sdk/solid";
+import type { TmNodeRef } from "@roku-sdk/interfaces";
+
+export const MeasuredTitle: Component<{ text: string; uri: string }> = props => {
+    const [fontRef, setFontRef] = createSignal<TmNodeRef>();
+    // The key restarts the wait when `uri` changes on this same <font> node.
+    const fontReady = createFontReady(fontRef, () => props.uri);
+    const [width, setWidth] = createSignal(0);
+
+    createEffect(() => {
+        if (!fontReady()) return;
+        const ref = fontRef();
+        if (!ref) return;
+        setWidth(getFontMeasure().getOneLineWidth(ref, props.text, 1920));
+    });
+
+    return (
+        <label
+            text={props.text}
+            width={width() || 600}
+            height={48}
+            color="0xFFFFFFFF"
+            font={<font uri={props.uri} size={32} ref={node => setFontRef(node.r)} />}
+        />
+    );
+};
+
+// Imperative form (same wait, no Solid helper):
+async function measureOnce(ref: TmNodeRef, text: string): Promise<number> {
+    await whenFontReady(ref);
+    return getFontMeasure().getOneLineWidth(ref, text, 1920);
+}
+```
+
+## Example
+
+A row of chevrons and a rating, using a bundled typeface — imported, sized, and with a fallback
+character for anything the typeface lacks.
+
+```tsx rsg-skill=complete
+import { BLACK_STAR, LEFT_BUTTON_GLYPH, RIGHT_BUTTON_GLYPH, WHITE_STAR } from "@roku-sdk/components/glyphs";
+import { Font, Label, LayoutGroup } from "@roku-sdk/components";
+
+import titleFontUri from "./fonts/title.ttf";
+
+function Rating(props: { filled: number; total: number }) {
+    return (
+        <label
+            text={BLACK_STAR.repeat(props.filled) + WHITE_STAR.repeat(props.total - props.filled)}
+            width={200}
+            height={48}
+            color="0xFFFFFFFF"
+        />
+    );
+}
+
+export function CarouselChrome(props: { title: string; rating: number }) {
+    return (
+        <layoutGroup layoutDirection="horiz" itemSpacings={[16]}>
+            {/* Private-use glyphs: the firmware fallback covers these even under a custom font. */}
+            <label text={LEFT_BUTTON_GLYPH} width={48} height={48} color="0xFFFFFFFF" />
+            <label
+                text={props.title}
+                width={600}
+                height={48}
+                color="0xFFFFFFFF"
+                // `size` is not optional in practice -- its default is 1 point,
+                // and a `Font` without a `uri` draws nothing at all.
+                font={<font uri={titleFontUri} size={32} />}
+            />
+            <Rating filled={props.rating} total={5} />
+            <label text={RIGHT_BUTTON_GLYPH} width={48} height={48} color="0xFFFFFFFF" />
+        </layoutGroup>
+    );
+}
+```
+
+## Anti-patterns
+
+Keyed by what you see on screen, because that is what arrives first.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Text shows empty boxes where symbols should be | The character is in neither font — geometric arrows like `◀` `▶` are the usual culprit | Use the named constant; `LEFT_ARROW` and friends are the shapes that exist |
+| Arrows, ticks and dashes vanished after the app shipped its own typeface | Those are RokuUI-Regular symbols and get no RokuFont01 backstop under a custom font | Keep them in system-font text, or make the custom typeface supply them |
+| Icons turned into unrelated shapes under a custom typeface | The custom font defines the same private-use codepoints and wins outright | Use a font without private-use glyphs, or draw those icons in system-font text |
+| Text renders at size 1 — a readable string, unreadably small | `Font.size` was left at its default | Set `size` whenever you set `uri` |
+| Changing the size does nothing at all | The `fontUri` names one of the eight fixed-size built-ins | Switch to `font:SystemFontFile` or a font file |
+| Characters from a backend show as boxes and `fallbackGlyph` changed nothing | It has no visible effect on current firmware, in either value form | Constrain the text or widen the typeface; do not keep tuning the value |
+| A label went completely blank after a `Font` node was added | The `Font` has a `size` but no `uri`, which draws nothing rather than falling back | Give it a `uri`, or drop the `Font` node and let the system font apply |
+| The build fails naming two font files | Same filename, different contents, keyed by filename | Rename one of them |
+| A private-use escape like `"\uE0nn"` sits in app code | The constant exists and the literal does not say which symbol it is | Import the constant |
+| Braces render literally in a label | Firmware placeholder syntax used as app text | Interpolate the constant |
+| `getFontMeasure` throws `"Font is not yet loaded"` or returns 0 | Measured before the GfxFont published; a fixed timer was too short | `await whenFontReady(ref)` or `createFontReady(fontRef)` — never a fixed timer |
+
+The glyph groups here are device-verified against firmware 15.3.5 on a Roku Express 4K+ — every
+constant rendered in a label under a custom typeface. Re-verify on a device rather than re-wording
+if you need to change what they claim. `IFontProps` and `ISimpleLabelProps` carry TSDoc in the
+installed package; prefer it over any prose, including this file, when the two disagree.

package/skills/fonts-and-glyphs/references/glyph-tables.md

@@ -0,0 +1,128 @@
+# Glyph tables
+
+45 constants, from `@roku-sdk/components/glyphs`. They are split into three tables here for the
+one reason that matters at runtime — **which font supplies the character** — because that, not the
+codepoint, decides whether a symbol survives a custom app typeface.
+
+| Group | Count | Under a system font | Under a custom app font |
+|---|---|---|---|
+| RokuFont01 private-use glyphs | 32 | renders | renders — firmware fallback applies |
+| Unicode characters RokuFont01 backs | 3 | renders | renders — same fallback |
+| RokuUI-Regular symbols | 10 | renders | **tofu**, unless the custom font supplies them |
+
+35 of the 45 are safe under a custom typeface. The ten that are not are the ones that look most
+ordinary, which is why this split is worth carrying.
+
+Verified on device twice, on different hardware and different firmware, by rendering the
+constants in a label with a custom TrueType font.
+
+- Roku Express 4K+, firmware 15.3.5: the private-use glyphs and the stars came through; `←` `↑`
+  `→` `↓` `✓` `✗` were empty boxes. `•` `…` `–` `—` rendered only because that particular font
+  happened to contain them — do not read that as a guarantee.
+- Roku Native (2910X), firmware 16.0.4, 1080p: same split. Under the system font every constant
+  rendered; under a custom TrueType the button glyphs and `★` `☆` rendered and `←` `→` `✓` were
+  boxes. The same run also showed a `Font` with a `uri` and no `size` drawing a speck, and
+  `fallbackGlyph` — as `u25CF` and as a literal `●` — leaving every box exactly as it was, both
+  for a RokuUI-only symbol and for a codepoint (`U+0E5B`, `U+A64B`) that no font on the device
+  has.
+
+The two runs agree, which is the point of having both: this split is a property of the firmware's
+font chain, not of one box.
+
+## 1. RokuFont01 — private-use glyphs (safe under a custom font)
+
+RokuFont01 is wired in as the system-wide fallback font in firmware, so these resolve wherever
+they appear.
+
+| Constant | Codepoint | Placeholder | Description |
+|---|---|---|---|
+| `OPTIONS_GLYPH` | `U+E000` | `{OPTIONS_GLYPH}` | Options / star (no border) |
+| `OK_BUTTON_GLYPH` | `U+E001` | `{OK_BUTTON_GLYPH}` | OK in circle |
+| `OPTIONS_BUTTON_GLYPH` | `U+E002` | `{OPTIONS_BUTTON_GLYPH}` | Options / star (with border) |
+| `MICROPHONE_GLYPH` | `U+E003` | `{MICROPHONE_GLYPH}` | Microphone (no border) |
+| `PLAY_PAUSE_BUTTON_GLYPH` | `U+E004` | `{PLAY_PAUSE_BUTTON_GLYPH}` | Play/pause (with border) |
+| `PLAY_PAUSE_GLYPH` | `U+E005` | `{PLAY_PAUSE_GLYPH}` | Play/pause (no border) |
+| `DOT_GLYPH` | `U+E006` | `{DOT_GLYPH}` | Baseline-aligned dot (icon-row form) |
+| `HOME_GLYPH` | `U+E007` | `{HOME_GLYPH}` | Home (no border) |
+| `SEARCH_GLYPH` | `U+E008` | `{SEARCH_GLYPH}` | Search / magnifying glass |
+| `REMOTE_GLYPH` | `U+E009` | `{REMOTE_GLYPH}` | Remote control |
+| `REPLAY_GLYPH` | `U+E010` | `{REPLAY_GLYPH}` | Instant replay |
+| `MICROPHONE_BUTTON_GLYPH` | `U+E011` | `{MICROPHONE_BUTTON_GLYPH}` | Microphone (with border) |
+| `SEARCH_BUTTON_GLYPH` | `U+E012` | `{SEARCH_BUTTON_GLYPH}` | Search (with border) |
+| `FAST_FORWARD_GLYPH` | `U+E013` | `{FAST_FORWARD_GLYPH}` | Fast forward |
+| `REWIND_GLYPH` | `U+E014` | `{REWIND_GLYPH}` | Rewind |
+| `SHORTCUT_ONE_BUTTON_GLYPH` | `U+E015` | `{SHORTCUT_ONE_BUTTON_GLYPH}` | Shortcut 1 |
+| `SHORTCUT_TWO_BUTTON_GLYPH` | `U+E016` | `{SHORTCUT_TWO_BUTTON_GLYPH}` | Shortcut 2 |
+| `CLOSED_CAPTIONS_GLYPH` | `U+E017` | `{CLOSED_CAPTIONS_GLYPH}` | Closed captions |
+| `LIVE_TV_GLYPH` | `U+E018` | `{LIVE_TV_GLYPH}` | Live TV |
+| `SLEEP_TIMER_GLYPH` | `U+E019` | `{SLEEP_TIMER_GLYPH}` | Sleep timer |
+| `GENERAL_APP_GLYPH` | `U+E020` | `{GENERAL_APP_GLYPH}` | General app icon |
+| `BACK_BUTTON_GLYPH` | `U+E021` | `{BACK_BUTTON_GLYPH}` | Back |
+| `HOME_BUTTON_GLYPH` | `U+E022` | `{HOME_BUTTON_GLYPH}` | Home button |
+| `QUICK_LAUNCH_BUTTON_GLYPH` | `U+E023` | `{QUICK_LAUNCH_BUTTON_GLYPH}` | Quick launch / rocket |
+| `DOWN_BUTTON_GLYPH` | `U+E024` | `{DOWN_BUTTON_GLYPH}` | Down |
+| `LEFT_BUTTON_GLYPH` | `U+E025` | `{LEFT_BUTTON_GLYPH}` | Left |
+| `RIGHT_BUTTON_GLYPH` | `U+E026` | `{RIGHT_BUTTON_GLYPH}` | Right |
+| `KIDS_PROFILE_GLYPH` | `U+E027` | `{KIDS_PROFILE_GLYPH}` | Kids profile |
+| `UP_BUTTON_GLYPH` | `U+E028` | `{UP_BUTTON_GLYPH}` | Up |
+| `POWER_BUTTON_GLYPH` | `U+E029` | `{POWER_BUTTON_GLYPH}` | Power |
+| `THUMBS_UP_GLYPH` | `U+E030` | `{THUMBS_UP_GLYPH}` | Thumbs up |
+| `THUMBS_DOWN_GLYPH` | `U+E031` | `{THUMBS_DOWN_GLYPH}` | Thumbs down |
+
+The numbering is decimal-style: the A–F slots in each decade (`U+E00A`–`U+E00F`, `U+E01A`–`U+E01F`,
+`U+E02A`–`U+E02F`) are unassigned. The font defines 32 private-use codepoints and the table lists
+all of them.
+
+`DOT_GLYPH` (`U+E006`) and `BLACK_CIRCLE` (`U+25CF`) are the same outline at two vertical
+positions — `DOT_GLYPH` sits on the baseline to line up with the other icon glyphs, `BLACK_CIRCLE`
+is raised to text centre for use inside a run of text. Both have full outline data; neither is
+reserved.
+
+## 2. Unicode characters RokuFont01 backs (safe under a custom font)
+
+Real Unicode codepoints, but RokuUI-Regular does not contain them — they resolve through the same
+RokuFont01 fallback as the private-use glyphs above. That makes them the *safe* shapes to use in
+custom-font text.
+
+| Constant | Codepoint | Char | Description |
+|---|---|---|---|
+| `BLACK_CIRCLE` | `U+25CF` | ● | Dot raised to text centre, for use inside a text run |
+| `BLACK_STAR` | `U+2605` | ★ | Filled star |
+| `WHITE_STAR` | `U+2606` | ☆ | Outlined star |
+
+## 3. RokuUI-Regular symbols (no backstop under a custom font)
+
+Part of the default UI font, so they need no fallback under a system font. Under a custom app font
+there is no RokuFont01 backstop for them either. **These are the ten constants to audit if your
+app ships its own typeface.**
+
+| Constant | Codepoint | Char | Description |
+|---|---|---|---|
+| `BULLET` | `U+2022` | • | Bullet |
+| `ELLIPSIS` | `U+2026` | … | Horizontal ellipsis |
+| `EN_DASH` | `U+2013` | – | En dash |
+| `EM_DASH` | `U+2014` | — | Em dash |
+| `LEFT_ARROW` | `U+2190` | ← | Leftwards arrow |
+| `UP_ARROW` | `U+2191` | ↑ | Upwards arrow |
+| `RIGHT_ARROW` | `U+2192` | → | Rightwards arrow |
+| `DOWN_ARROW` | `U+2193` | ↓ | Downwards arrow |
+| `CHECK_MARK` | `U+2713` | ✓ | Check mark |
+| `BALLOT_X` | `U+2717` | ✗ | Ballot X |
+
+## What has no constant, on purpose
+
+Characters you can type directly get none: `·` middle dot, `°` degree, currency signs, maths
+operators, quotation marks. Type them. A constant would add a name to look up without adding
+anything the compiler or the device cares about.
+
+Geometric arrows `◀` and `▶` are in **neither** font and have no constants because they do not
+render. Reach for `LEFT_ARROW` / `RIGHT_ARROW`, or the bordered `LEFT_BUTTON_GLYPH` /
+`RIGHT_BUTTON_GLYPH` when you want the remote-button look.
+
+## Firmware placeholders
+
+The `{CONSTANT_NAME}` column above is the firmware's own placeholder syntax, used in translated
+firmware strings and resolved by the firmware's string layer. It is not a TypeScript symbol and it
+is not template syntax: putting `{BACK_BUTTON_GLYPH}` in a label renders those braces literally.
+Use the placeholder form only where you are explicitly producing text for something that resolves
+firmware placeholders, and interpolate the imported constant everywhere else.

package/skills/logging-and-errors/SKILL.md

@@ -0,0 +1,227 @@
+# Logging and Errors
+
+## Overview
+
+An RSG SDK TypeScript app reports what it is doing through one exported `logger`, and survives a
+throw through Solid's `ErrorBoundary`. Both have a platform edge that catches people out: log
+levels are enforced in **two** places, one of which deletes your call before the app ever runs,
+and the SDK already wraps every screen in a boundary whose fallback draws nothing — so the
+default shape of a failure here is a blank screen rather than a crash.
+
+## When to Use
+
+- a log level raised and nothing new appears
+- log levels configured somewhere that turns out to have no effect
+- `console` calls present while developing and gone from the build handed over
+- a screen that comes up blank with no crash and no stack
+- containing a throw so one bad screen does not take the app with it, or recovering afterwards
+- an uncaught-exception handler that never fires, or fires and then behaves unexpectedly
+- a crash stack that cannot be traced back to the TypeScript that produced it
+
+### When not to use
+
+| Situation | Use instead | Because |
+|---|---|---|
+| Getting logs **off** a device from a shell script or a CI job | The `cli-dev-loop` skill | This skill is about a line being emitted; collecting it afterwards is a different surface |
+| Getting logs off a device, or decoding a stack, inside an agent session | The `mcp-ai-dev-loop` skill | Same distinction, reached through tool calls rather than a shell |
+| What the running app costs in frames, memory or startup time | The `app-performance` skill | Instrumenting for cost is measurement, not reporting |
+| Which Solid primitives `@roku-sdk/solid` exports at all | The `solid-on-roku` skill | This skill owns the failure, not the export surface |
+
+## Read the reference first for this task
+
+| If the request is | Read now, before answering |
+|---|---|
+| Writing or debugging a `setUncaughtExceptionHandler` callback | `references/uncaught-exceptions.md` |
+
+The tables below say that the handler exists, what it never sees, and that registering one cannot
+be undone. Its timeout, its inverted `done` flag and the conditions under which it silently does
+nothing are only in the reference, and a handler written from the summary alone is wrong in ways
+that do not show up until something throws in production.
+
+## Quick Reference
+
+| Question | Answer |
+|---|---|
+| Get a logger | `import { logger } from "@roku-sdk/rsg-ts"` — the root one; `logger.getLogger("myscreen")` for a child |
+| Levels available | `trace`, `debug`, `info`, `warn`, `error`. There is no `fatal`, and `createLogger` is not exported |
+| Why a message is a function | `logger.info(() => \`...\`)` — the thunk is only invoked once the level check passes, so a filtered line costs nothing to build |
+| The two level knobs | `app.logger.baseLogLevel` **deletes** call sites at build time (default INFO in production builds); `app.logger.currentLogLevel` filters what remains at runtime (default ERROR; also enforced as a runtime backstop at the base level) |
+| Which one to raise | Whichever is higher wins. Raising only `currentLogLevel` recovers nothing a lower `baseLogLevel` already deleted |
+| Setting levels via `buildVariables` | A silent no-op — the build overwrites `__BASE_LOG_LEVEL__` and `__CURRENT_LOG_LEVEL__` itself |
+| Contain a throw | `<ErrorBoundary fallback={…}>` around the subtree, from `@roku-sdk/solid` |
+| Recover from one | `catchError` for a scoped throw, `resetErrorBoundaries` to retry every boundary |
+| Blank screen, no crash, no stack | The SDK's own boundary caught a root-component throw. One `error` line under source `btstp` is the entire evidence |
+| `console` in a shipped build | Dropped by `rk build`, kept by `rk dev`; `dropConsole: false` keeps them, and then `installConsolePolyfill()` restores the helpers |
+| Trace a stack back to TypeScript | Call `enableExceptionTagging()` before the code that can throw. Inside `main()`, before the anchor node, covers throws after `main()`; a throw at module top level needs the call in the entry file's first import |
+| An uncaught-exception handler | `setUncaughtExceptionHandler` — never sees an `ErrorBoundary` catch, sees nothing thrown before it registers, and registration is permanent |
+| Where these live | `logger`, `main`, `enableExceptionTagging` and `setUncaughtExceptionHandler` all come from `@roku-sdk/rsg-ts`; `installConsolePolyfill` only from `@roku-sdk/native` |
+
+## Instructions
+
+1. **Log through the exported `logger`, and give each area a child.** `logger` is the root;
+   `logger.getLogger("playback")` tags that area's lines. `createLogger` is deliberately module
+   private, so a child logger is the only sanctioned way to get a distinct source.
+
+2. **Pass a thunk, not a string.** Every method takes `() => string`. The level check runs first,
+   so an interpolation inside the thunk is never paid for on a filtered line. Building the string
+   at the call site throws that away.
+
+3. **Understand which level does what, because only one of them can be undone.**
+   - `baseLogLevel` is a **build-time** cut. Any statement calling a method below it is replaced
+     with `void 0;` in the source before the bundler sees it, so the call is not in the artifact
+     at all. Nothing at runtime can bring it back.
+   - `currentLogLevel` is a **runtime** filter over whatever survived, resolved once at module
+     load.
+
+   So diagnose in that order: if a line is missing, ask whether it was deleted before asking
+   whether it was filtered. The defaults are `INFO` for the base cut and `ERROR` for the runtime
+   filter, which is why a `debug` line is absent from a default build twice over.
+
+4. **Know what the build-time cut checks and what it does not.** It matches a whole expression
+   statement whose call target is a log method (e.g. `.trace`, `.debug`) on a receiver that is
+   recognised as an SDK logger binding in that file. Specifically, the receiver must be:
+   - A named import of `logger` (or an aliased import) from one of the SDK logger modules
+     (`@roku-sdk/rsg-ts` or `@roku-sdk/common`), or common's own relative `./logger` import.
+   - A child logger derived from any of the above via `const X = logger.getLogger("area")`
+     (and any further `.getLogger(…)` chains at module level).
+   - An inline `logger.getLogger("a").debug(…)` call in statement position.
+
+   Non-SDK receivers (`someLibrary.debug(…)`, `console.debug(…)`, `myEmitter.trace(…)`) are
+   never removed. Shadowing is respected: when a local binding reuses the name — any parameter
+   (constructor, accessor and destructured ones included), a `catch` binding, a loop variable, or
+   a local declaration — calls through it are left untouched.
+
+   One documented limitation: a logger exported from one module and re-imported under a
+   *different* import path (not one of the recognised specifiers) is not recognised by the
+   per-file pass and is not stripped at build time. The runtime backstop (see below) still
+   silences it. The sanctioned pattern is: import `logger` from the SDK and derive children
+   with `getLogger` in the same module.
+
+   A second limitation: inside a function, only a child derived directly from a recognised SDK
+   logger is stripped. A grandchild built from a function-local child — `const a =
+   logger.getLogger("a"); const b = a.getLogger("b"); b.debug(…)`, or inline
+   `a.getLogger("b").debug(…)` — is kept at build time. Like the case above, this only ever
+   leaves a call in (never removes a non-SDK one), and the runtime backstop still silences it.
+   Derive nested children at module level if you want them stripped.
+
+   Child loggers must be declared with `const`. A `let` or `var` child
+   (`let l = logger.getLogger("x")`) can be reassigned to some other object, so its calls are
+   kept at build time rather than risk deleting app code. The runtime backstop still silences them.
+
+   Only a bare statement is stripped. `const line = logger.debug(…)`, or a call guarded by
+   `&&`, survives — so a log statement written in an unusual shape will not be stripped as
+   expected.
+
+5. **Set levels in `app.logger`, never in `buildVariables`.** The two keys the logger reads are
+   `__BASE_LOG_LEVEL__` and `__CURRENT_LOG_LEVEL__`, and the build writes both itself —
+   unconditionally, after copying your `buildVariables` — then restores them only from
+   `app.logger`. So a value you put in `buildVariables` under either name is overwritten with an
+   empty string, which the reader treats exactly like an unset variable. You get the defaults,
+   with no warning that your setting was discarded.
+
+6. **Wrap a subtree that can throw in `ErrorBoundary`, and draw something in the fallback.** The
+   SDK already puts one boundary around the whole app, and its fallback returns nothing — so an
+   uncontained throw in a root component is a blank screen rather than a crash. That is the SDK
+   working as designed, not a missing feature. Your own boundary, closer to the risk, is what
+   turns it into a message the user can act on.
+
+7. **Recover with `catchError` or `resetErrorBoundaries`.** `catchError` handles a throw inside
+   one computation without unmounting a subtree; `resetErrorBoundaries` re-runs every boundary's
+   children, which is the "try again" button's implementation.
+
+8. **Expect `console` to disappear from the build you hand over.** `rk build` drops `console.*`
+   and `debugger`; `rk dev` keeps them. Set `dropConsole: false` when a build must keep them
+   on purpose — and note the helper methods (`count`, `group`, `assert` and the timing pair) come
+   from a polyfill that only auto-installs in a development build, so a production build that
+   keeps `console` also needs `installConsolePolyfill()` from `@roku-sdk/native`. Plain
+   `console.log`, `warn` and `error` are the runtime's own and are never wrapped. None of this
+   replaces `logger`: `console` has no levels, no sources and no build-time cut.
+
+9. **Call `enableExceptionTagging()` before the code that can throw**, when traces from this
+   build have to be resolvable later. Inside `main()`, before registering the anchor node, covers
+   throws from the `main()` callback onward. A throw while the bundle is still being evaluated
+   needs the call in the same module the entry file imports first (step 10). It marks each trace
+   with the build's source-map identity. It is idempotent, and calling it costs nothing at runtime
+   beyond the tagging itself. Turning a captured stack back into TypeScript afterwards is
+   `cli-dev-loop` from a shell and `mcp-ai-dev-loop` from a session — this step is only the app's half.
+
+10. **Reach for `setUncaughtExceptionHandler` only for what a boundary cannot catch**, and read
+    the reference before writing one. It replaces the SDK's default permanently, it never sees a
+    throw an `ErrorBoundary` already caught, and it is not the mechanism behind the blank screen
+    in step 6. It also misses anything thrown before it registers, and every module's top-level
+    code runs before `main()` is called. When a module can throw at its top level, register in
+    the entry file's first import rather than inside `main()`.
+
+## Render-thread transaction errors
+
+On firmware with `roku.Transaction.setErrorCallback`, SDK `main()` installs a default
+error-level logger under source `tx` before declaring app components. It reports each
+render-thread transaction error with its reason, message and available operation, node ID
+and property name. These asynchronous errors do not throw through `ErrorBoundary` or the
+uncaught-exception handler. Apps calling `roku.Transaction.setErrorCallback` themselves
+replace this default; accessors are valid only during that callback. Older firmware without
+the callback API is unchanged and cannot surface these errors through this SDK handler.
+
+## Example
+
+An app entry point that tags its traces, and a screen that contains its own failures instead of
+letting the SDK's blank fallback have them.
+
+```tsx rsg-skill=complete
+import { Label, LayoutGroup } from "@roku-sdk/components";
+import { type AnchorNodeImplementation, defineAnchorNode, FieldType, logger } from "@roku-sdk/rsg-ts";
+import { ErrorBoundary } from "@roku-sdk/solid";
+
+const screenLog = logger.getLogger("playback");
+
+const PlaybackScreenDescription = {
+    componentName: "PlaybackScreen",
+    extends: "Group" as const,
+    inputFields: {
+        assetId: FieldType.String("")
+    },
+    outputFields: {}
+};
+
+function NowPlaying(props: { assetId: string }) {
+    // The thunk is only invoked once the level check passes.
+    screenLog.info(() => `rendering asset ${props.assetId}`);
+    return <label text={props.assetId} width={800} height={48} color="0xFFFFFFFF" />;
+}
+
+const PlaybackScreen: AnchorNodeImplementation<typeof PlaybackScreenDescription> = inputs => (
+    <layoutGroup layoutDirection="vert">
+        <ErrorBoundary
+            fallback={error => {
+                // Without a fallback that draws, this subtree is simply absent.
+                screenLog.error(() => `playback failed: ${error.message}`);
+                return <label text="Playback unavailable" width={800} height={48} color="0xFF6666FF" />;
+            }}
+        >
+            <NowPlaying assetId={inputs.assetId ?? ""} />
+        </ErrorBoundary>
+    </layoutGroup>
+);
+
+export default defineAnchorNode(PlaybackScreenDescription, PlaybackScreen);
+```
+
+## Common Mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| A level was raised, the app rebuilt, and the lines are still missing | `baseLogLevel` deleted the call sites; raising the runtime filter cannot restore a call that is not in the artifact | Raise `app.logger.baseLogLevel` and rebuild |
+| Levels set through `buildVariables` change nothing, and nothing warns | The build overwrites `__BASE_LOG_LEVEL__` and `__CURRENT_LOG_LEVEL__` with an empty string before restoring them from `app.logger` | Set them in `app.logger` |
+| A screen is blank, the app is still running, and there is no stack | A root component threw and the SDK's own boundary caught it; its fallback draws nothing | Search the log for source `btstp`; add your own `ErrorBoundary` closer to the risk |
+| An `ErrorBoundary` was added and the screen is still blank | The `fallback` returns nothing, or the boundary sits above the component that throws rather than around it | Return a real node from `fallback`; put the boundary around the risky subtree |
+| An uncaught-exception handler never fires for a render-time throw | A boundary caught it first, and the handler only sees what nothing caught | Handle it in the boundary; keep the handler for what escapes |
+| The app exits from the splash screen, and the handler never fires | A module threw at its top level while the bundle was evaluated, before the handler was registered inside `main()` | Register in a module the entry file imports first, as a bare `import "./…"` |
+| A registered handler cannot be swapped back to the SDK default | Registration replaces the default permanently, by design | Register once, at startup, and branch inside your own handler |
+| A handler was registered and does nothing at all, silently | `globalThis.Process` was unavailable, so the call warned and returned — and at the default runtime filter that warning is itself invisible | Read the reference; confirm the handler registers where the runtime provides it |
+| Diagnostics print in development and are gone from the shipped build | `rk build` drops `console.*` by default | Use `logger`, or set `dropConsole: false` deliberately |
+| `console` timing and grouping helpers are missing in a build that kept `console` | The polyfill auto-installs only in a development build | Call `installConsolePolyfill()` from `@roku-sdk/native` |
+| A captured stack cannot be matched to a build | The app never tagged its traces, or tagged them inside `main()` after a module had already thrown | Call `enableExceptionTagging()` before that code. Inside `main()` covers throws after it; a module top-level throw needs the call in the entry file's first import |
+
+`Logger`, `setUncaughtExceptionHandler` and `ErrorBoundary` are typed with TSDoc in the installed
+packages. Read an option there rather than guessing its name, and prefer it over any prose,
+including this file, when the two disagree.