Spatial Navigation for GeckoView

A GeckoView web extension providing WICG-compatible spatial navigation for Android TV, AAOS, and D-pad/keyboard navigation. Designed for seamless integration with flutter-geckoview and other GeckoView host applications.

Features

Core Navigation

✅ Geometric spatial navigation - Multi-pass scoring algorithm for accurate directional navigation
✅ Focus groups - Define navigation regions with data-focus-group attributes
✅ WICG API compatibility - window.navigate(), Element.spatialNavigationSearch(), etc.
✅ Visual focus overlay - Animated amber outline with directional previews
✅ Scroll container awareness - Handles nested scrollable regions

Platform Integration

✅ Native messaging - Bidirectional communication with GeckoView host apps
✅ Focus exit events - Notify native app when navigation leaves web content
✅ Config updates - Runtime configuration from native layer

Advanced Features

✅ Shadow DOM traversal - Works with Web Components (Shoelace, Material Web)
✅ Virtual scroll detection - Automatic refresh for React Virtualized, YouTube, Twitter
✅ Focus trap detection - Handles modals/dialogs with escape affordances
✅ ARIA accessibility - Optional live region announcements
✅ Framework-aware refresh - Deferred updates for React/Vue/Angular
✅ Strict TypeScript - Fully typed codebase with noImplicitAny: true
✅ Performance - <5ms navigation latency (benchmarked for 1000+ elements)

Installation

GitHub Packages (npm)

# Configure npm to use GitHub Packages for @dart-technologies scope
echo "@dart-technologies:registry=https://npm.pkg.github.com" >> .npmrc

# Install the package
npm install @dart-technologies/spatial-navigation-geckoview

Git Submodule (recommended for flutter-geckoview)

For Flutter/native projects that bundle the extension as an asset:

# Add as submodule
git submodule add https://github.com/dart-technologies/spatial-navigation-geckoview.git lib/assets/spatial_navigation

# Initialize and update
git submodule update --init --recursive

# Build the extension
cd lib/assets/spatial_navigation
npm install
npm run build:all

Update submodule to latest:

cd lib/assets/spatial_navigation
git pull origin main
npm install
npm run build:all
cd ../../..
git add lib/assets/spatial_navigation
git commit -m "chore: update spatial-navigation-geckoview submodule"

Manual Installation

Clone and build:

git clone https://github.com/dart-technologies/spatial-navigation-geckoview.git
cd spatial-navigation-geckoview
npm install
npm run build:all

Usage

GeckoView Integration

// Install extension in GeckoView
runtime.webExtensionController
    .ensureBuiltIn(
        "resource://android/assets/spatial_navigation/",
        "spatial-navigation@geckoview.dev"
    )
    .accept(
        { extension -> 
            Log.i("SpatialNav", "Extension installed: ${extension.id}")
            setupMessageDelegate(extension)
        },
        { error -> Log.e("SpatialNav", "Install failed", error) }
    )

// Handle messages from extension
private fun setupMessageDelegate(extension: WebExtension) {
    extension.setMessageDelegate(object : WebExtension.MessageDelegate {
        override fun onMessage(
            nativeApp: String,
            message: Any,
            sender: WebExtension.MessageSender
        ): GeckoResult<Any>? {
            val json = message as? JSONObject ?: return null
            when (json.getString("type")) {
                "spatialNavInit" -> Log.d("SpatialNav", "Initialized: ${json.getString("url")}")
                "focusExit" -> handleFocusExit(json.getString("direction"))
            }
            return null
        }
    }, "geckoview-spatial-nav")
}

Web Page Configuration

<!-- Optional: Configure via global -->
<script>
  window.spatialNavConfig = {
    color: '#00BCD4',           // Teal focus color
    outlineWidth: 4,
    autoRefocus: true,
    enableAria: true,           // Enable accessibility
    traverseShadowDom: true,    // For Web Components
  };
</script>

<!-- Focus groups for navigation regions -->
<nav data-focus-group="main-nav;boundary=contain">
  <button>Home</button>
  <button>Search</button>
</nav>

<main data-focus-group="content;enterMode=last">
  <!-- Content area remembers last focused element -->
</main>

Programmatic Navigation

// WICG-compatible API
window.navigate('down');    // Move focus down
window.navigate('right');   // Move focus right

// Find next target without moving
const next = document.activeElement.spatialNavigationSearch('down');
console.log('Next target:', next);

// Get focusable elements in container
const focusables = document.body.focusableAreas({ mode: 'visible' });

// Get navigation container
const container = button.getSpatialNavigationContainer();

Configuration

All options can be set via window.spatialNavConfig:

Visual Options

Option	Type	Default	Description
`color`	string	`'#FFC107'`	Focus highlight color (amber)
`outlineWidth`	number	`3`	Outline width in CSS pixels
`outlineOffset`	number	`3`	Outline offset in CSS pixels
`overlayZIndex`	number	`2147483646`	Overlay z-index
`arrowScale`	number	`1.0`	Directional chevron scale
`disabledColor`	string	`'128, 128, 128'`	Disabled/boundary indicator RGB string
`overlayTheme`	string	`'default'`	`'default'` or `'high-contrast'` preset
`safeAreaMargin`	number	`12`	Safe-area/overscan margin in CSS pixels
`overlayScrimOpacity`	number	`0.06`	Inner scrim opacity (0–1)
`overlayGlowOpacity`	number	`0.35`	Outer glow opacity (0–1)
`overlayGlowBlur`	number	`14`	Outer glow blur radius in CSS pixels
`autoRefocus`	boolean	`true`	Recover focus when lost

Observation Options

Option	Type	Default	Description
`observeMutations`	boolean	`true`	Watch for DOM changes
`observeScroll`	boolean	`true`	Update on scroll
`traverseShadowDom`	boolean	`false`	Recurse into Shadow DOM
`observeVirtualContainers`	boolean	`true`	Detect virtual scroll
`enableAria`	boolean	`false`	Enable ARIA announcements
`focusTrapDetection`	boolean	`false`	Detect modals/dialogs
`precomputeCandidates`	boolean	`true`	Background pre-computation

Scoring Options

Option	Type	Default	Description
`scoringMode`	string	`'geometric'`	Algorithm: `'geometric'` or `'grid'`
`distanceFunction`	string	`'euclidean'`	Distance: `'euclidean'`, `'manhattan'`, `'projected'`
`overlapThreshold`	number	`0`	Pixels of overlap allowed (BBC LRUD)
`gridAlignmentTolerance`	number	`20`	Pixels tolerance for grid alignment
`wrapNavigation`	boolean	`false`	Wrap focus at container boundaries
`useCSSProperties`	boolean	`true`	Read `--spatial-navigation-*` CSS

Focus Group Options

<div data-focus-group="id;boundary=contain;enterMode=last;remember=true">

boundary: exit (default), contain, wrap, stop
enterMode: default, first, last
remember: true (default), false

Events

Navigation Events (WICG-compatible)

// Before focus changes (cancelable)
document.addEventListener('navbeforefocus', (e) => {
  console.log('Moving', e.detail.dir, 'to', e.target);
  // e.preventDefault() to cancel
});

// When hitting boundary
document.addEventListener('navnotarget', (e) => {
  console.log('Boundary reached:', e.detail.dir);
  if (e.detail.inTrap) {
    console.log('In trap, escape:', e.detail.escapeKey);
  }
});

Focus Exit Events

// When navigation leaves web content
document.addEventListener('spatialNavigationExit', (e) => {
  console.log('Exiting web content:', e.detail.direction);
  // Native app handles from here
});

Native Messaging Protocol

Messages from Extension → Native

Type	Payload	Description
`spatialNavInit`	`{ url, version }`	Extension initialized
`focusChange`	`{ direction, fromElement, toElement }`	Focus moved
`focusExit`	`{ direction, inTrap }`	Reached boundary

Messages from Native → Extension

Type	Payload	Description
`navigate`	`{ direction }`	Request navigation
`configUpdate`	`{ ...config }`	Update config
`refresh`	`{}`	Re-scan focusables

Building

# Install dependencies
npm install

# Build all outputs
npm run build:all

# Build minified only
npm run build

# Build debug (unminified)
npm run build:debug

# Run tests
# Run tests
npm test

# Run performance benchmarks
npm run test:benchmark

Output Files

File	Format	Size	Use Case
`dist/spatial-navigation.js`	UMD	~20KB	General usage
`dist/spatial-navigation.esm.js`	ESM	~20KB	Modern bundlers
`dist/spatial-navigation.extension.js`	IIFE	~20KB	GeckoView extension
`dist/spatial-navigation.debug.js`	IIFE	~50KB	Development

Comparison with Other Libraries

vs WICG Polyfill

Feature	WICG Polyfill	This Extension
W3C API	Full	Partial
CSS Properties	Yes	Yes
Visual Overlay	No	Yes
Native Messaging	No	Yes
Virtual Scroll	No	Yes

vs Pathduck/spatialnavigation

Feature	Pathduck	This Extension
Sections	Yes	Focus Groups
Visual Feedback	Class only	Animated overlay
React/Vue	No	Framework-aware
Shadow DOM	No	Yes

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
__tests__		__tests__
core		core
e2e		e2e
extension		extension
messaging		messaging
navigation		navigation
scripts		scripts
src		src
utils		utils
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
background.ts		background.ts
globals.d.ts		globals.d.ts
main.ts		main.ts
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

Spatial Navigation for GeckoView

Features

Core Navigation

Platform Integration

Advanced Features

Installation

GitHub Packages (npm)

Git Submodule (recommended for flutter-geckoview)

Manual Installation

Usage

GeckoView Integration

Web Page Configuration

Programmatic Navigation

Configuration

Visual Options

Observation Options

Scoring Options

Focus Group Options

Events

Navigation Events (WICG-compatible)

Focus Exit Events

Native Messaging Protocol

Messages from Extension → Native

Messages from Native → Extension

Building

Output Files

Comparison with Other Libraries

vs WICG Polyfill

vs Pathduck/spatialnavigation

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages