Add initial Nebula Core packages and docs

Import initial monorepo structure for Nebula Core: add packages (@nebula/core, core-glyphs, core-input, core-navigation, core-theme, core-ui, core-utils) with source, dist, tests and assets. Expand README with overview, quick start and API snippets, and add package-level documentation files. Add jsconfig.json for path mapping, package.json and lockfiles to bootstrap the repo. This commit sets up the project layout, docs, and local package links for further development.

documentation/core-glyphs.md

@@ -0,0 +1,22 @@
+# @nebula/core-glyphs
+
+Controller glyph mappings and lookup helpers. Data-only, no rendering logic.
+
+## What it does
+
+- Maps logical actions to glyph labels per controller type.
+- Provides asset path lookups for common glyphs.
+- Keeps glyph decisions centralized and consistent.
+
+## Included data and helpers
+
+- `glyphMap` — Action-to-label mappings per controller type.
+- `glyphAssetMap` — Action-to-asset-path mappings per controller type.
+- `getGlyph(controller, action)` — Resolve a label.
+- `getGlyphAssetPath(controller, action)` — Resolve an asset path.
+
+## Typical use cases
+
+- Displaying correct prompts for Steam Deck, Xbox, PlayStation, or Switch.
+- Using consistent glyph labels in UI and localization.
+- Swapping controller visuals based on detected device.

documentation/core-input.md

@@ -0,0 +1,21 @@
+# @nebula/core-input
+
+Action-based input abstraction for controller-first apps. Converts raw device events into app-level actions.
+
+## What it does
+
+- Normalizes device input into a consistent `InputEvent` shape.
+- Maps physical controls to logical actions (e.g. confirm, back).
+- Emits action updates with `value` and `active` state.
+
+## Key concepts
+
+- **InputEvent**: Normalized event with `source`, `control`, `type`, and `value`.
+- **InputBinding**: Maps a physical control to an action name.
+- **ActionUpdate**: The emitted result when an input matches a binding.
+
+## Typical use cases
+
+- Gamepad-first UIs that should work across Deck, Xbox, and PlayStation layouts.
+- Unified handling of keyboard and controller inputs without coupling to hardware.
+- Action-driven UI logic (confirm/back/menu) instead of button-driven logic.

documentation/core-navigation.md

@@ -0,0 +1,20 @@
+# @nebula/core-navigation
+
+Focus management and spatial navigation primitives for controller-first UIs.
+
+## What it does
+
+- Calculates spatial relationships between focusable rectangles.
+- Filters candidates by direction (up/down/left/right).
+- Picks the best next focus target using a weighted distance heuristic.
+
+## Key concepts
+
+- **Rect**: A focusable element described by `x`, `y`, `width`, `height`, and `id`.
+- **Direction**: The requested movement direction (up/down/left/right).
+
+## Typical use cases
+
+- D-pad or stick navigation across grids and lists.
+- Consistent focus movement in TV or handheld UIs.
+- Simple focus logic without a framework dependency.

documentation/core-theme.md

@@ -0,0 +1,23 @@
+# @nebula/core-theme
+
+Theme tokens tuned for readable, couch-friendly UI. Exports plain objects and helpers only.
+
+## What it does
+
+- Provides a default token set for colors, spacing, typography, radius, and motion.
+- Lets you merge overrides with `createTheme()` for custom styling.
+- Keeps everything as plain objects for easy use in any UI layer.
+
+## Token groups
+
+- **colors**: Background, surface, text, accent, focus, danger.
+- **spacing**: XS through XXL spacing scale.
+- **radius**: Corner radius presets.
+- **typography**: Caption, body, title, display sizes.
+- **motion**: Fast/base/slow durations.
+
+## Typical use cases
+
+- Consistent visual system across packages and apps.
+- Theme customization without framework coupling.
+- Readable defaults for TV and handheld screens.

documentation/core-ui.md

@@ -0,0 +1,21 @@
+# @nebula/core-ui
+
+Minimal UI helpers for controller-first applications. No framework lock-in.
+
+## What it does
+
+- Defines recommended hit target sizes for controller navigation.
+- Provides focus ring tokens for visible focus styling.
+- Builds minimal focusable attributes for DOM-based UIs.
+
+## Included helpers
+
+- `hitTarget` — Minimum dimensions for interactive elements.
+- `focusRing` — Outline width/color/offset for focus indication.
+- `getFocusableAttributes(options)` — Returns `role`, `tabIndex`, and `data-` attributes.
+
+## Typical use cases
+
+- Ensuring touch and controller targets are large enough.
+- Consistent focus styling in custom UI frameworks.
+- Simple DOM attribute helpers for focus management.

documentation/core-utils.md

@@ -0,0 +1,22 @@
+# @nebula/core-utils
+
+Small, dependency-free utilities shared across Nebula Core packages. No DOM or platform assumptions.
+
+## What it does
+
+- Provides tiny, reusable math helpers.
+- Exposes a minimal event emitter for small, decoupled messaging.
+- Stays platform-agnostic so it works in browser, Electron, or Node.
+
+## Included utilities
+
+- `clamp(value, min, max)` — Clamp a number between bounds.
+- `lerp(from, to, t)` — Linear interpolation between two numbers.
+- `roundTo(value, decimals)` — Round to a fixed decimal precision.
+- `createEmitter()` — Lightweight emitter with `on`, `emit`, and `clear`.
+
+## Typical use cases
+
+- Input or navigation modules needing small math helpers.
+- App-level messaging without pulling in larger event libraries.
+- Shared helpers across packages in the monorepo.