Making Rc3 the default now (#80)

* fix Marquee case on export

* Release 3.0.0-9

* update core

* Release 3.0.0-10

* Revert "fix up focus of children being added after column/row is created"

This reverts commit fec6923.

* Release 3.0.0-11

* only check selected if row / column doesnt have focus already

* Release 3.0.0-12

* Release 3.0.0-13

* Suspense forwardFocus, Lazy to add to offset if selected

* update buffer for auto which is default

* Release 3.0.0-14

* Spatial navigation and refactor (#61)

* Cleanup and rename col/row navigation helpers

* Add spatial navigation helpers

* Refactor navigation functions to improve selection logic and simplify child focus handling

* Fix onGridFocus no scroll issue

* Refactor onGridFocus to use optional parameter syntax

* Rename getDistanceBetweenRects to getWeightedDistanceBetweenRects and update logic to calculate distances based on center and edge positions.

* Enhance navigableForwardFocus to include lastSelected in onSelectedChanged callback

* Use findFirstSelectableChildIdx in moveSelection

* Refactor selectChild to handle null children and update onSelectedChanged callback

* Refactor navigableForwardFocus to simplify focus checking and update selected child logic

* Only check for skipfocus for selectable child

* Use findFirstFocusableChildIdx in navigableForwardFocus

* Add idxInArray to cleanup code

* Switch to calculating rect dist from centers

* Use new navigable helpers in row and col

* Fix selection logic in moveSelection to handle skipFocus correctly

* Add jsdoc to navigation helpers

* Rename navigable helpers and add examples

* Correct calculating child rect
Depends on lightning-tv/core#66

* update to latest core

* Release 3.0.0-15

* refocus children

* Release 3.0.0-16

* call onSelectedChanged on focus

* Release 3.0.0-17

* Fix tests (#66)

* Add scrollColumn and scrollRow helpers (#68)

* working with latest beta

* Release 3.0.0-18

* update to latest core / renderer b15

* Release 3.0.0-19

* only setFocus if the row has focus

* merge main, update core + renderer

* Release 3.0.0-20

* merge core back into solid, one project

* fix transitions for width and height, now w & h

* Release 3.0.0-21

* copy over additional changes from main branch

* add back in source to package

* handle negative selected input

* fix up contain & sprite maps

* teaks to contain for text

* Release 3.0.0-22

* add fontWeightAlias to help migrate

* add migration guide

* add rounded with border shader

* Release 3.0.0-23

* fix calling scrollToIndex(0)

* create tags at bottom corner so not visible to users

* add more performant rounded shader

* Release 3.0.0-24

* run lint:fix

* add article, fps 1 alpha

* fix packages

* fix up build with latest renderer

* fix prettier issues

* fix up tests

* feat(focus): pass nodeWithCallback to focus handlers
Updates `onFocus`, `onBlur`, and `onFocusChanged` callbacks to receive the node triggering the event as the last argument.

* address issue where node sizes can be negative if parentHeight-y

* fix dual package hazard - types of renderer must match

* Release 3.0.0-25

* fix global types

* Release 3.0.0-26

* fix jsx-runtime import

* Release 3.0.0-27

---------

Co-authored-by: Damian Tarnawski <[email protected]>

Author: chiefcll

docs/_sidebar.md

@@ -1,5 +1,7 @@
 - Articles
   - [Basics](/articles/basics.md)
+  - [Migration 2.x to 3.0](/articles/migration-2x-to-3.0.md)
+  - [Boosting LightningJS Performance by 50%](/articles/boostingperf.md)
   - [Real World Performance](/articles/realworldperformance.md)
   - [Solid / Blits Framework Comparison](/articles/solidvsblits.md)
 - Essentials

docs/articles/boostingperf.md

@@ -0,0 +1,140 @@
+<style>
+  img {
+      transition: transform 0.25s ease;
+  }
+
+  img:hover {
+      -webkit-transform: scale(1.8);
+      transform: scale(1.8);
+      position: relative;
+      z-index: 5;
+  }
+</style>
+
+# Boosting LightningJS Performance by 50%
+
+LightningJS has earned its reputation as a fast and capable framework for building TV applications. When Lightning 2.0 emerged, it set a new bar for what was possible on constrained TV hardware, offering a WebGL-based renderer that was lightweight, approachable for web developers, and performant enough to run smoothly even on most TV devices. For many teams, it became the de facto standard, and for good reason.
+
+That legacy matters. LightningJS is a solid idea, built on a strong architectural foundation. Using WebGL for TV UIs is a smart choice, and the renderer exists thanks to a tremendous amount of thoughtful engineering. Credit is due to the people who carried Lightning this far; shout out to Frank and Jeffrey for building something that has enabled an entire ecosystem of TV applications.
+
+Lightning 3.0 was introduced with the promise of moving that success forward. In some areas, it does. Node creation is faster, the internal structure is more modern, and the ambition to evolve the framework is clear. The potential is absolutely there. But in practice, especially on real TV hardware, Lightning 3 has not yet delivered the performance improvements many of us were hoping for.
+
+This article is not a critique for its own sake. It is a call to the community and to the LightningJS team to focus together on what made Lightning successful in the first place: real, measurable performance on real devices.
+
+---
+
+## Building on Lightning 3 in the Real World
+
+Over the last year, I built a SolidJS integration on top of the Lightning 3 renderer with a clear goal: to provide a highly performant, developer-friendly way to build production-grade TV apps.
+
+From a developer experience perspective, the results were encouraging. SolidJS proved to be an excellent match: fine-grained reactivity, predictable updates, and access to a large, healthy open-source ecosystem. Teams enjoyed building with it, iteration was fast, and initial page loads were snappy.
+
+However, once these applications reached real TV hardware, the experience changed. While startup performance was good, and pages loaded quickly, interaction performance was inconsistent. Animations felt heavier than expected. Basic navigation, something TV UIs must excel at, often fails to meet the smoothness bar users intuitively expect.
+
+After extensive profiling and testing, one thing became clear: SolidJS was not the limiting factor. The bottleneck was the Lightning JS Renderer itself.
+
+---
+
+## From Assumptions to Evidence
+
+Initially, it was reasonable to assume hardware limitations were the cause. TV devices are underpowered, and pushing pixels is expensive. Maybe 30 fps was the best that could be achieved? Maybe the latest beta of Lightning 3 Renderer will improve performance…
+
+Instead, nearly a year after Lightning 3’s release, progress has centered around a prolonged beta with breaking changes but little measurable performance improvement. Text rendering has improved a bit. But these changes don’t help the render loop.
+
+The original authors of Lightning 2 and Lightning 3 are no longer involved. With that transition, some of the hard-won institutional knowledge around renderer performance appears to have faded.
+
+At the same time, there is a prevailing sense that the renderer is already well-optimized and continuing to improve. Unfortunately, extensive profiling and real-device testing do not support that conclusion. This disconnect creates a real risk: without deep familiarity with the renderer’s internals, performance issues can be underestimated, misdiagnosed, or deprioritized.
+
+At this stage, meaningful gains will not come from surface-level changes, but from deliberate, informed work in the renderer’s hot paths. This is precisely the moment for renewed focus, not complacency. If LightningJS is to regain its performance leadership, rebuilding that depth of understanding must be treated as a priority.
+
+---
+
+## A Breaking Point: When “Good Enough” Wasn’t
+
+One client project made the situation impossible to ignore. The UI was intentionally simple: a hero section at the top, followed by horizontally scrolling rows of content tiles. This is a common, well-understood TV layout, and it was aggressively optimized at the application level.
+
+The feedback from the boss:
+
+> “Scrolling between rows feels a bit slow on the box. Can we make it smoother?”
+
+At that point, there was nothing left to optimize in the application code. The framework layer had been pushed as far as it reasonably could. The remaining bottleneck was the renderer.
+
+So I started examining the renderer itself.
+
+---
+
+## Understanding the Renderer
+
+Over the course of a month, I profiled the renderer deeply: the update loop, node lifecycle, shader switching, draw calls, garbage generation, and how state changes propagate frame to frame. This meant digging into WebGL internals and understanding exactly where time and memory were being spent.
+
+WebGL is powerful, but it does not make performance problems disappear. At the end of the day, this is still JavaScript running tight loops on constrained hardware. Every allocation matters. Every unnecessary branch matters. Every redundant calculation matters. And in its current form, the renderer was simply doing too much work per frame.
+
+---
+
+## Fixing What Was Already There
+
+One of the first discoveries was the number of subtle but impactful bugs in the renderer. These were not failures that caused crashes, but inefficiencies that quietly compounded over time. The update loop, in particular, was performing significant unnecessary work each frame, amplifying performance costs on constrained hardware.
+
+I attempted to address these issues upstream by opening numerous pull requests. While some small fixes were ultimately accepted as bug corrections, discussion around performance implications was nonexistent, and to make an impactful performance difference would require a large refactor of the core.
+
+This experience highlighted a broader challenge. Despite being positioned as a community-driven open-source project, there is limited transparency into current priorities, performance goals, or the renderer roadmap. Without clear signals around what is being optimized, why certain changes matter, or how contributors can meaningfully engage, collaboration is impossible.
+
+This lack of clarity is also visible in long-standing feature requests with clear user impact. Right-to-left text support, for example, has been requested since January 2025, yet there is still no visible roadmap or guidance on when or how it will be addressed. This effectively excludes entire regions and languages from fully adopting LightningJS, not because of technical limitations, but because of prioritization.
+
+Similarly, magic mouse support was started but never completed. After waiting without clarity on timelines or ownership, I ultimately implemented full support directly within the SolidJS integration in order to ship production applications over a year ago.
+
+These are not edge cases. They illustrate a broader pattern: when priorities are opaque and follow-through is uncertain, contributors are forced to work around the platform rather than build alongside it.
+
+---
+
+## Garbage Collection: A Silent Performance Killer
+
+Garbage collection proved to be another major factor.
+
+On TV hardware, GC is unforgiving. Allocations inside high-frequency loops, temporary arrays, short-lived objects, and implicit allocations inevitably lead to unpredictable stutters when the collector runs.
+
+The renderer was generating garbage continuously during the render loop. By restructuring this logic to reduce allocations as much as possible, the impact was immediate. GC pauses became rarer and shorter, and animations stopped hitching unpredictably.
+
+This is not about clever tricks or clean code; it’s about respecting the realities of constrained devices. Reducing garbage pressure is critical to overall application performance.
+
+---
+
+## Doing Less Work Per Frame
+
+A third major area of improvement was caching.
+
+A surprising amount of work was being recomputed every frame, even when nothing had changed. By aggressively caching results and skipping unchanged states, the renderer simply did less work per frame. I still have a bunch of additional ideas to pursue in this area.
+
+---
+
+## Real-World Results
+
+After fixing bugs in the update loop, eliminating garbage in hot paths, and caching work, the forked renderer consistently outperforms the upstream LightningJS renderer by approximately 50% in real-world scenarios.
+
+Testing was done on a Raspberry Pi 3, a constrained device that closely mirrors the performance characteristics of low-end TV hardware. Using Lightning 3 beta v20, the upstream renderer averaged around 30 FPS in a representative TV UI. With the forked changes applied, the same application on the same device consistently exceeded 45 FPS.
+
+These numbers come from real hardware, not desktop simulations, and the difference is immediately visible to end users.
+
+Watch the video for yourself:
+[Youtube](https://www.youtube.com/watch?v=byM5IzrLKJE)
+
+---
+
+## Looking Forward
+
+At this point, continuing to upstream these changes no longer feels productive. The performance issues have been clearly identified, fixes have been proposed, and ample time has passed for review and discussion. That process has not resulted in meaningful action.
+
+At the same time, this work represents a significant investment of time, expertise, and real-world validation. It would be irresponsible to discard it or indefinitely delay its use while teams shipping production applications continue to struggle with performance constraints.
+
+For that reason, I am choosing a different path. The renderer improvements will be shared directly with the clients I work with, ensuring they can deliver the level of performance their products require. In parallel, I am exploring whether there is broader interest in accessing these updates and what a fair valuation for that work might be.
+
+This is not an attempt to fragment the ecosystem, but to acknowledge reality. Historically, competition has been one of the most reliable drivers of innovation in open-source and platform ecosystems. When progress stalls, alternative implementations often serve as the catalyst for renewed focus, clearer priorities, and better outcomes for everyone involved.
+
+---
+
+To learn more and get involved:
+
+- **Official Website**: [lightningtv.dev](https://lightningtv.dev)
+- **GitHub Repository**: [github.com/lightning-tv/solid](https://github.com/lightning-tv/solid)
+- **Community Discord**: [Discord](https://discord.gg/HEqckxcB)
+- **Connect with Me**: [Chris Lorenzo on LinkedIn](https://www.linkedin.com/in/chris-lorenzo/)

docs/articles/migration-2x-to-3.0.md

@@ -0,0 +1,138 @@
+# Migration Guide: Lightning 3 v2.x to v3.0
+
+This guide helps you migrate from Lightning 3 version 2.x to the new 3.0 release. The 3.0 version introduces several breaking changes to improve performance and the Solid integration has done a lot of under the hood changes to improve performance and reduce the amount of code you need to update.
+
+To get the full list of changes from the renderer you can check the [changelog](https://github.com/lightning-tv/renderer/blob/main/CHANGELOG.md).
+
+### Fonts
+
+`fontWeight` was removed from the renderer and is now polyfilled by Solid. When you load fonts with different weights, ie `Roboto` 400 and 700, you'll need to update your fonts with different fontFamily names:
+
+```typescript
+{
+    type: "msdf",
+    fontFamily: "Roboto",
+    atlasDataUrl: basePath + "fonts/Roboto-Regular.msdf.json",
+    atlasUrl: basePath + "fonts/Roboto-Regular.msdf.png"
+  } as const,
+  {
+    type: "msdf",
+    fontFamily: "Roboto700",
+    atlasDataUrl: basePath + "fonts/Roboto-Bold.msdf.json",
+    atlasUrl: basePath + "fonts/Roboto-Bold.msdf.png"
+  } as const,
+```
+
+Notice we removed the descriptor with the weight. Long term you can just change the fontFamily to change fonts.
+
+To help with migration we have exposed a fontWeightAlias that maps common font weights to their numeric values. You can override this in your config if needed.
+
+```typescript
+Config.fontWeightAlias = {
+    thin: 100,
+    light: 300,
+    regular: '',
+    400: '',
+    medium: 500,
+    bold: 700,
+    black: 900,
+},
+```
+
+Setting `fontWeight` to 700 is now a function that does the following:
+
+```typescript
+set fontWeight(v) {
+  this._fontWeight = v;
+  const family = this.fontFamily || Config.fontSettings?.fontFamily;
+  const weight =
+    (Config.fontWeightAlias &&
+      (Config.fontWeightAlias[v as string] as number | string)) ??
+    v;
+  this.fontFamily = `${family}${weight}`;
+}
+```
+
+#### Enhanced Font Metrics
+
+Lightning 3.0 provides better font metrics support:
+
+```typescript
+// Recommended: Always provide font metrics for optimal rendering
+await stage.loadFont('canvas', {
+  fontFamily: 'MyFont',
+  fontUrl: '/fonts/my-font.ttf',
+  metrics: {
+    ascender: 800, // Font ascender in font units
+    descender: -200, // Font descender in font units
+    lineGap: 0, // Additional line spacing
+    unitsPerEm: 1000, // Font units per EM
+  },
+});
+```
+
+### Width/Height Property Changes
+
+The `width` and `height` properties were changed in favor of shorter `w` and `h` properties for by the Lightning team.
+
+Width and height are still available but are now polyfilled by Solid. Note that in some places like Shaders you may need to use `w` and `h` instead of `width` and `height`.
+
+Oh and some properties are still `maxWidth` and `maxHeight`. 🤷
+
+### Texture Loaded Event Changes
+
+The texture loaded event now reports dimensions using `w` and `h` properties:
+
+```typescript
+// v2.x - Dimensions with width/height
+node.on('loaded', (event) => {
+  if (event.type === 'texture') {
+    console.log('Texture loaded:', {
+      width: event.dimensions.width, // ⚠️ No longer available
+      height: event.dimensions.height, // ⚠️ No longer available
+    });
+  }
+});
+
+// v3.0 - Dimensions with w/h
+node.on('loaded', (event) => {
+  if (event.type === 'texture') {
+    console.log('Texture loaded:', {
+      w: event.dimensions.w, // ✅ Available
+      h: event.dimensions.h, // ✅ Available
+    });
+  }
+});
+```
+
+## Updated Shaders
+
+Shaders are imported when needed by application. The following example shows how to import and register shaders:
+
+```typescript
+const { renderer, render } = createRenderer();
+loadFonts(fonts);
+// Prepare for RC3 of Renderer
+import {
+  Rounded,
+  RoundedWithBorder,
+  RoundedWithShadow,
+  RoundedWithBorderAndShadow,
+  RadialGradient,
+  LinearGradient,
+  HolePunch,
+} from '@lightningjs/renderer/webgl/shaders';
+const shManager = renderer.stage.shManager;
+shManager.registerShaderType('rounded', Rounded);
+shManager.registerShaderType('roundedWithBorder', RoundedWithBorder);
+shManager.registerShaderType('roundedWithShadow', RoundedWithShadow);
+shManager.registerShaderType(
+  'roundedWithBorderWithShadow',
+  RoundedWithBorderAndShadow,
+);
+shManager.registerShaderType('radialGradient', RadialGradient);
+shManager.registerShaderType('linearGradient', LinearGradient);
+shManager.registerShaderType('holePunch', HolePunch);
+```
+
+Be mindful some of the properties may have changed (like width/height).

docs/primitives/useFocusManager.md

@@ -39,10 +39,10 @@ const App = () => {
 
 The `useFocusManager` returns a signal, `focusPath`, which is an array of elements that currently have focus. When the `activeElement` changes, the focus path is recalculated. During this process:
 
-- All elements in focus will have a `focus` state added, and `onFocus(currentFocusedElm, prevFocusedElm)` event is called.
-- Elements losing focus will have the `focus` state removed, and `onBlur(currentFocusedElm, prevFocusedElm)` event is called.
+- All elements in focus will have a `focus` state added, and `onFocus(currentFocusedElm, prevFocusedElm, nodeWithCallback)` event is called.
+- Elements losing focus will have the `focus` state removed, and `onBlur(currentFocusedElm, prevFocusedElm, nodeWithCallback)` event is called.
 
-There is also an `onFocusChanged(hasFocus, currentFocusedElm, prevFocusedElm)` callback which is useful for setting a focusSignal to use for more complicated scenarios.
+There is also an `onFocusChanged(hasFocus, currentFocusedElm, prevFocusedElm, nodeWithCallback)` callback which is useful for setting a focusSignal to use for more complicated scenarios.
 
 ```jsx
 const [hasFocus, setHasFocus] = createSignal(false);
@@ -71,7 +71,7 @@ You can now control input speed in two powerful ways . This feature helps preven
 For a quick, app-wide solution, you can set a global throttle on all key inputs directly in your configuration. This is perfect for setting a baseline input speed for your entire application.
 
 ```javascript
-import { Config } from '@lightningtv/core';
+import { Config } from '@lightningtv/solid';
 
 // Allow one keypress every 200ms across the entire app
 Config.throttleInput = 200;

docs/primitives/virtual.md

@@ -52,7 +52,6 @@ Use `cursor` property on the node to get the absolute index in the list of items
 - Automatically re-calculates the slice on selection or data change.
 - Reuses Children components
 - Merges styles with internal layout defaults:
-
   - `display: flex`, `flexWrap: wrap`, `gap: 30`
   - `transition: { y: 250ms ease-out }`
 

docs/primitives/virtualgrid.md

@@ -60,7 +60,6 @@ import { VirtualGrid } from './components/VirtualGrid';
 - Automatically re-calculates the slice on selection or data change.
 - Reuses Children components
 - Merges styles with internal layout defaults:
-
   - `display: flex`, `flexWrap: wrap`, `gap: 30`
   - `transition: { y: 250ms ease-out }`
 

jsx-runtime.d.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-namespace */
-import type { NodeProps, TextProps } from '@lightningtv/core';
+import type { NodeProps, TextProps } from './src/core/index.js';
 
 declare module 'solid-js' {
   namespace JSX {