@qodin-co/sol 0.1.3 → 0.1.4

package/README.md

@@ -1,470 +1,451 @@
-<div align="center">
-
-<img src=".github/banner.png" alt="@qodin-co/sol — solar-aware React widgets" width="100%" />
-
-<br />
-<br />
-
-<a href="https://www.npmjs.com/package/@qodin-co/sol">
-  <img src="https://img.shields.io/npm/v/@qodin-co/sol?style=flat-square&color=111&labelColor=111&logo=npm" alt="npm version" />
-</a>
-<a href="https://www.npmjs.com/package/@qodin-co/sol">
-  <img src="https://img.shields.io/npm/dm/@qodin-co/sol?style=flat-square&color=111&labelColor=111" alt="npm downloads" />
-</a>
-<a href="https://github.com/qodin-co/sol/blob/main/LICENSE">
-  <img src="https://img.shields.io/npm/l/@qodin-co/sol?style=flat-square&color=111&labelColor=111" alt="license" />
-</a>
-<a href="https://github.com/qodin-co/sol/actions/workflows/validate.yml">
-  <img src="https://img.shields.io/github/actions/workflow/status/qodin-co/sol/validate.yml?style=flat-square&color=111&labelColor=111&label=ci" alt="CI" />
-</a>
-
-<br />
-<br />
-
-**Solar-aware React widgets that follow the real position of the sun.**
-
-[npm](https://www.npmjs.com/package/@qodin-co/sol) · [GitHub](https://github.com/qodin-co/sol) · withsol.app — launching soon
-
-</div>
-
----
-
-```bash
-bun add @qodin-co/sol
-# or
-npm install @qodin-co/sol
-```
-
-`@qodin-co/sol` gives you a full `SolarWidget`, a `CompactWidget`, 10 skins, 9 solar phases, optional live weather, optional flag display, and a dev-only timeline scrubber via `SolarDevTools`. No solar API required — solar position is computed locally from latitude, longitude, timezone, and current time.
-
----
-
-## Features
-
-- **2 widget variants** — `SolarWidget` (full card) and `CompactWidget` (slim pill/bar)
-- **10 skins** — `foundry`, `paper`, `signal`, `meridian`, `mineral`, `aurora`, `tide`, `void`, `sundial`, `parchment`
-- **9 solar phases** — `midnight`, `night`, `dawn`, `sunrise`, `morning`, `solar-noon`, `afternoon`, `sunset`, `dusk`
-- **Built-in fallback strategy** — geolocation → browser timezone → timezone centroid
-- **Optional live weather** — powered by Open-Meteo (no API key required)
-- **Dev preview tooling** — `SolarDevTools` lets you scrub through the day and preview phase colors
-
----
-
-## Installation
-
-Import the package styles once at your app root — no Tailwind setup required:
-
-```ts
-import '@qodin-co/sol/styles.css';
-```
-
----
-
-## Quick Start
-
-### 1. Wrap your app
-
-```tsx
-import '@qodin-co/sol/styles.css';
-import { SolarThemeProvider } from '@qodin-co/sol';
-
-export function AppProviders({ children }: { children: React.ReactNode }) {
-  return (
-    <SolarThemeProvider initialSkin="foundry">
-      {children}
-    </SolarThemeProvider>
-  );
-}
-```
-
-### 2. Render a widget
-
-```tsx
-import { SolarWidget } from '@qodin-co/sol';
-
-export default function Page() {
-  return (
-    <SolarWidget
-      skin="foundry"
-      showWeather
-      showFlag
-      hoverEffect
-    />
-  );
-}
-```
-
-### 3. Or use the compact variant
-
-```tsx
-import { CompactWidget } from '@qodin-co/sol';
-
-export default function HeaderStatus() {
-  return (
-    <CompactWidget
-      skin="signal"
-      showWeather
-      showFlag
-      size="md"
-    />
-  );
-}
-```
-
----
-
-## Provider Setup
-
-`SolarThemeProvider` is the shared runtime for solar phase computation, timezone, coordinates, skin selection, and live/manual overrides.
-
-### Basic
-
-```tsx
-<SolarThemeProvider initialSkin="paper">
-  <App />
-</SolarThemeProvider>
-```
-
-### Location is automatic
-
-`SolarThemeProvider` resolves the user's location automatically using a 3-step fallback:
-
-1. **Browser Geolocation API** — most accurate (requires user permission)
-2. **Browser timezone** (`Intl.DateTimeFormat`) — instant, no permission needed
-3. **Timezone centroid lookup** — maps the IANA timezone to approximate city coordinates
-
-Solar phases are accurate to ~15–30 minutes from timezone alone, and refine to exact values when geolocation is granted.
-
-### Override location (optional)
-
-```tsx
-<SolarThemeProvider
-  initialSkin="meridian"
-  latitude={37.7749}
-  longitude={-122.4194}
-  timezone="America/Los_Angeles"
->
-  <App />
-</SolarThemeProvider>
-```
-
-> These props override automatic resolution. Omit them to let Sol detect location automatically.
-
-### With global CSS variables
-
-```tsx
-<SolarThemeProvider applyThemeToDocument initialSkin="aurora">
-  <App />
-</SolarThemeProvider>
-```
-
-Exposes variables like `--solar-accent`, `--solar-bg-base`, `--solar-text-primary` for use in your own styles.
-
-### Provider Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `children` | `ReactNode` | — | Required |
-| `initialSkin` | `DesignMode` | `'foundry'` | Default skin |
-| `skin` | `DesignMode` | — | Controlled skin override |
-| `onSkinChange` | `(skin: DesignMode) => void` | — | Callback when skin changes |
-| `applyThemeToDocument` | `boolean` | `false` | Write CSS vars + data attrs to `<html>` |
-| `latitude` | `number \| null` | — | Explicit latitude override |
-| `longitude` | `number \| null` | — | Explicit longitude override |
-| `timezone` | `string \| null` | — | Explicit IANA timezone override |
-
----
-
-## SolarWidget
-
-```tsx
-<SolarWidget
-  skin="foundry"
-  position="bottom-right"
-  expandDirection="top-left"
-  size="lg"
-  showWeather
-  showFlag
-  hoverEffect
-/>
-```
-
-### Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `skin` | `DesignMode` | provider skin | Skin override for this widget |
-| `position` | `AnchorPosition \| 'inline'` | `'inline'` | Fixed viewport anchoring |
-| `expandDirection` | `AnchorPosition` | `'bottom-right'` | Direction the card opens |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'lg'` | Widget size |
-| `showWeather` | `boolean` | `false` | Enable live weather display |
-| `showFlag` | `boolean` | `false` | Show country flag |
-| `hoverEffect` | `boolean` | `false` | Enable hover animation |
-| `phaseOverride` | `SolarPhase \| null` | — | Force a discrete phase |
-| `timeOverride` | `Date \| null` | — | Simulate a specific time |
-| `weatherCategoryOverride` | `WeatherCategory \| null` | — | Force weather condition |
-| `customPalettes` | `Partial<Record<SolarPhase, { bg: [string, string, string] }>>` | — | Override phase colors |
-| `className` | `string` | — | Wrapper CSS class |
-| `style` | `CSSProperties` | — | Wrapper inline style |
-
----
-
-## CompactWidget
-
-```tsx
-<CompactWidget
-  skin="signal"
-  size="md"
-  showWeather
-  showFlag
-  showTemperature
-/>
-```
-
-### Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `skin` | `DesignMode` | provider skin | Skin override |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Compact size |
-| `showWeather` | `boolean` | `false` | Show weather icon |
-| `showFlag` | `boolean` | `false` | Show country flag |
-| `showTemperature` | `boolean` | `true` | Show live temperature |
-| `phaseOverride` | `SolarPhase \| null` | — | Force a discrete phase |
-| `timeOverride` | `Date \| null` | — | Simulate a time |
-| `weatherCategoryOverride` | `WeatherCategory \| null` | — | Force weather condition |
-| `className` | `string` | — | Wrapper CSS class |
-| `style` | `CSSProperties` | — | Wrapper inline style |
-
----
-
-## Skins
-
-10 skins, each with a full widget and compact variant. If `skin` is omitted on a widget, it uses the provider's active skin.
-
-```ts
-type DesignMode =
-  | 'aurora'      // luminous ethereal
-  | 'foundry'     // warm volumetric industrial
-  | 'tide'        // fluid organic wave
-  | 'void'        // minimal negative space
-  | 'mineral'     // faceted crystal gem
-  | 'meridian'    // hairline geometric
-  | 'signal'      // pixel/blocky lo-fi
-  | 'paper'       // flat ink editorial
-  | 'sundial'     // roman/classical carved
-  | 'parchment';  // document strokes
-```
-
----
-
-## Positioning
-
-```tsx
-<SolarWidget />                                                         // inline (default)
-<SolarWidget position="bottom-right" />                                 // fixed to viewport
-<SolarWidget position="bottom-right" expandDirection="top-left" />      // with expand direction
-```
-
-Supported positions: `top-left` `top-center` `top-right` `center-left` `center` `center-right` `bottom-left` `bottom-center` `bottom-right` `inline`
-
----
-
-## Weather
-
-```tsx
-<SolarWidget showWeather />
-
-// Force a category for preview
-<SolarWidget showWeather weatherCategoryOverride="thunder" />
-```
-
-Powered by [Open-Meteo](https://open-meteo.com/) — free, no API key. Available categories: `clear` `partly-cloudy` `overcast` `fog` `drizzle` `rain` `heavy-rain` `snow` `heavy-snow` `thunder`
-
----
-
-## Phase & Time Overrides
-
-```tsx
-// Force a discrete phase
-<SolarWidget phaseOverride="sunset" />
-
-// Simulate a specific time (with blend)
-const preview = new Date();
-preview.setHours(6, 45, 0, 0);
-<SolarWidget timeOverride={preview} />
-```
-
-Use `timeOverride` for realistic continuous previews. Use `phaseOverride` for simple hard overrides.
-
----
-
-## Custom Palettes
-
-```tsx
-<SolarWidget
-  skin="foundry"
-  customPalettes={{
-    dawn:   { bg: ['#20122a', '#7f3b5d', '#f5a66e'] },
-    sunset: { bg: ['#2e0f18', '#b84a3d', '#ffbe7a'] },
-  }}
-/>
-```
-
----
-
-## SolarDevTools
-
-A dev-only bottom-fixed pill for scrubbing through the day. Imported from a dedicated subpath — never included in production bundles unless explicitly imported.
-
-```tsx
-import { SolarDevTools } from '@qodin-co/sol/devtools';
-
-// Vite
-{import.meta.env.DEV && <SolarDevTools />}
-
-// Next.js
-{process.env.NODE_ENV === 'development' && <SolarDevTools />}
-```
-
-### Full example
-
-```tsx
-import '@qodin-co/sol/styles.css';
-import { SolarThemeProvider, SolarWidget } from '@qodin-co/sol';
-import { SolarDevTools } from '@qodin-co/sol/devtools';
-
-export default function Demo() {
-  return (
-    <SolarThemeProvider initialSkin="foundry">
-      <SolarWidget showWeather showFlag />
-      {process.env.NODE_ENV === 'development' && (
-        <SolarDevTools position="bottom-center" />
-      )}
-    </SolarThemeProvider>
-  );
-}
-```
-
-### Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `defaultOpen` | `boolean` | `false` | Start expanded |
-| `position` | `'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-center'` | Pill position |
-| `enabled` | `boolean` | `true` | Programmatic enable/disable |
-
----
-
-## useSolarTheme
-
-```tsx
-import { useSolarTheme } from '@qodin-co/sol';
-
-function DebugPanel() {
-  const { phase, timezone, latitude, longitude, design } = useSolarTheme();
-  return (
-    <pre>{JSON.stringify({ phase, timezone, latitude, longitude, design }, null, 2)}</pre>
-  );
-}
-```
-
-### Return shape
-
-| Property | Type | Description |
-|---|---|---|
-| `phase` | `SolarPhase` | Current active phase |
-| `blend` | `SolarBlend` | Phase blend state (phase, nextPhase, t) |
-| `isDaytime` | `boolean` | Whether the sun is above the horizon |
-| `brightness` | `number` | 0–1 brightness value |
-| `mode` | `'light' \| 'dim' \| 'dark'` | Current light mode |
-| `accentColor` | `string` | Active accent hex |
-| `timezone` | `string \| null` | Resolved timezone |
-| `latitude` | `number \| null` | Resolved latitude |
-| `longitude` | `number \| null` | Resolved longitude |
-| `coordsReady` | `boolean` | Whether coordinates have resolved |
-| `design` | `DesignMode` | Active skin name |
-| `activeSkin` | `SkinDefinition` | Full skin definition object |
-| `setOverridePhase` | `(phase \| null) => void` | Set/clear phase override |
-| `setDesign` | `(skin: DesignMode) => void` | Change active skin |
-
----
-
-## Multiple Widgets
-
-```tsx
-<SolarThemeProvider initialSkin="foundry">
-  <SolarWidget skin="foundry" position="bottom-left" showWeather />
-  <CompactWidget skin="signal" />
-  <SolarWidget skin="aurora" position="bottom-right" />
-</SolarThemeProvider>
-```
-
-Each widget can have its own skin. The provider manages shared solar state.
-
----
-
-## TypeScript
-
-```ts
-import type {
-  DesignMode,
-  SolarPhase,
-  SolarBlend,
-  WeatherCategory,
-  ExpandDirection,
-  WidgetSize,
-  CompactSize,
-  SkinDefinition,
-  WidgetPalette,
-  SolarTheme,
-} from '@qodin-co/sol';
-```
-
----
-
-## SSR / Hydration Notes
-
-Sol is client-aware and uses browser APIs for geolocation, timezone, and storage. The provider falls back safely when coordinates are not yet resolved. Use the `ClientOnly` wrapper if you encounter hydration mismatches in SSR frameworks.
-
----
-
-## What's Included
-
-| | |
-|---|---|
-| ✅ | Full widget + compact widget |
-| ✅ | 10 skins with full + compact variants |
-| ✅ | Solar math (NOAA equations, no external API) |
-| ✅ | Timezone fallback logic |
-| ✅ | Optional live weather (Open-Meteo) |
-| ✅ | Skin-aware country flags |
-| ✅ | Dev timeline scrubber |
-| ✅ | Compiled CSS (no Tailwind required) |
-| ❌ | No solar API key needed |
-| ❌ | No weather API key needed |
-| ❌ | No Tailwind in your app |
-| ❌ | No geolocation permission required |
-
----
-
-## Coming Soon
-
-**SOL** website is launching soon — a dedicated site for Sol with full documentation, live skin previews, and a playground to explore every phase and skin combination.
-
-Sol is actively being developed. Things in progress:
-
-- **Seasonal theme system** — 4 seasons (Summer, Autumn, Winter, Spring) that blend automatically with the existing 9-phase system, computed from date and location with no configuration required
-- More skins
-- Vue and Svelte adapters
-- Deep token override system
-
-Follow the repo or watch releases to stay updated.
-
----
-
-<div align="center">
-
-MIT © [qodin](https://github.com/qodin-co)
-
+<div align="center">
+
+<img src=".github/banner.png" alt="@qodin-co/sol — solar-aware React widgets" width="100%" />
+
+<br />
+<br />
+
+<a href="https://www.npmjs.com/package/@qodin-co/sol">
+  <img src="https://img.shields.io/npm/v/@qodin-co/sol?style=flat-square&color=111&labelColor=111&logo=npm" alt="npm version" />
+</a>
+<a href="https://www.npmjs.com/package/@qodin-co/sol">
+  <img src="https://img.shields.io/npm/dm/@qodin-co/sol?style=flat-square&color=111&labelColor=111" alt="npm downloads" />
+</a>
+<a href="https://github.com/qodin-co/sol/blob/main/LICENSE">
+  <img src="https://img.shields.io/npm/l/@qodin-co/sol?style=flat-square&color=111&labelColor=111" alt="license" />
+</a>
+<a href="https://github.com/qodin-co/sol/actions/workflows/validate.yml">
+  <img src="https://img.shields.io/github/actions/workflow/status/qodin-co/sol/validate.yml?style=flat-square&color=111&labelColor=111&label=ci" alt="CI" />
+</a>
+
+<br />
+<br />
+
+**Solar-aware React widgets that follow the real position of the sun.**
+
+[npm](https://www.npmjs.com/package/@qodin-co/sol) · [GitHub](https://github.com/qodin-co/sol) · withsol.app — launching soon
+
+</div>
+
+---
+
+```bash
+bun add @qodin-co/sol
+# or
+npm install @qodin-co/sol
+```
+
+`@qodin-co/sol` gives you a full `SolarWidget`, a `CompactWidget`, 10 skins, 9 solar phases, optional live weather, optional flag display, and a dev-only timeline scrubber via `SolarDevTools`. No solar API required — solar position is computed locally from latitude, longitude, timezone, and current time.
+
+---
+
+## Features
+
+- **2 widget variants** — `SolarWidget` (full card) and `CompactWidget` (slim pill/bar)
+- **10 skins** — `foundry`, `paper`, `signal`, `meridian`, `mineral`, `aurora`, `tide`, `void`, `sundial`, `parchment`
+- **9 solar phases** — `midnight`, `night`, `dawn`, `sunrise`, `morning`, `solar-noon`, `afternoon`, `sunset`, `dusk`
+- **Built-in fallback strategy** — geolocation → browser timezone → timezone centroid
+- **Optional live weather** — powered by Open-Meteo (no API key required)
+- **Dev preview tooling** — `SolarDevTools` lets you scrub through the day and preview phase colors
+
+---
+
+## Installation
+
+Import the package styles once at your app root — no Tailwind setup required:
+
+```ts
+import '@qodin-co/sol/styles.css';
+```
+
+---
+
+## Quick Start
+
+### 1. Wrap your app
+
+```tsx
+import '@qodin-co/sol/styles.css';
+import { SolarThemeProvider } from '@qodin-co/sol';
+
+export function AppProviders({ children }: { children: React.ReactNode }) {
+  return (
+    <SolarThemeProvider initialDesign="foundry">
+      {children}
+    </SolarThemeProvider>
+  );
+}
+```
+
+### 2. Render a widget
+
+```tsx
+import { SolarWidget } from '@qodin-co/sol';
+
+export default function Page() {
+  return (
+    <SolarWidget
+      showWeather
+      showFlag
+      hoverEffect
+    />
+  );
+}
+```
+
+### 3. Or use the compact variant
+
+```tsx
+import { CompactWidget } from '@qodin-co/sol';
+
+export default function HeaderStatus() {
+  return (
+    <CompactWidget
+      design="signal"
+      showWeather
+      showFlag
+      size="md"
+    />
+  );
+}
+```
+
+---
+
+## Provider Setup
+
+`SolarThemeProvider` is the shared runtime for solar phase computation, timezone, coordinates, skin selection, and live/manual overrides.
+
+### Basic
+
+```tsx
+<SolarThemeProvider initialDesign="paper">
+  <App />
+</SolarThemeProvider>
+```
+
+### Location is automatic
+
+`SolarThemeProvider` resolves the user's location automatically using a 3-step fallback:
+
+1. **Browser Geolocation API** — most accurate (requires user permission)
+2. **Browser timezone** (`Intl.DateTimeFormat`) — instant, no permission needed
+3. **Timezone centroid lookup** — maps the IANA timezone to approximate city coordinates
+
+Solar phases are accurate to ~15–30 minutes from timezone alone, and refine to exact values when geolocation is granted.
+
+### Override location (optional)
+
+```tsx
+<SolarThemeProvider
+  initialDesign="meridian"
+>
+  <App />
+</SolarThemeProvider>
+```
+
+> These props override automatic resolution. Omit them to let Sol detect location automatically.
+
+### With global CSS variables
+
+```tsx
+<SolarThemeProvider initialDesign="aurora">
+  <App />
+</SolarThemeProvider>
+```
+
+### Provider Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Required |
+| `initialDesign` | `DesignMode` | `'foundry'` | Default design/skin |
+| `isolated` | `boolean` | `false` | Scope CSS vars to wrapper instead of `:root` |
+
+---
+
+## SolarWidget
+
+```tsx
+<SolarWidget
+  expandDirection="top-left"
+  size="lg"
+  showWeather
+  showFlag
+  hoverEffect
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `expandDirection` | `ExpandDirection` | `'bottom-right'` | Direction the card opens |
+| `size` | `WidgetSize` | `'lg'` | Widget size |
+| `showWeather` | `boolean` | `false` | Enable live weather display |
+| `showFlag` | `boolean` | `false` | Show country flag |
+| `hoverEffect` | `boolean` | `false` | Enable hover animation |
+| `phaseOverride` | `SolarPhase` | — | Force a discrete phase |
+| `simulatedDate` | `Date` | — | Simulate a specific time |
+| `weatherCategoryOverride` | `WeatherCategory \| null` | — | Force weather condition |
+| `customPalettes` | `CustomPalettes` | — | Override phase colors |
+| `forceExpanded` | `boolean` | — | Lock expanded/collapsed state |
+
+---
+
+## CompactWidget
+
+```tsx
+<CompactWidget
+  design="signal"
+  size="md"
+  showWeather
+  showFlag
+  showTemperature
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `design` | `DesignMode` | provider design | Design/skin override |
+| `size` | `CompactSize` | `'md'` | Compact size |
+| `showWeather` | `boolean` | `false` | Show weather icon |
+| `showFlag` | `boolean` | `false` | Show country flag |
+| `showTemperature` | `boolean` | `true` | Show live temperature |
+| `overridePhase` | `SolarPhase \| null` | — | Force a discrete phase |
+| `simulatedDate` | `Date` | — | Simulate a time |
+| `className` | `string` | — | Wrapper CSS class |
+
+---
+
+## Skins
+
+10 designs, each with a full widget and compact variant. If `design` is omitted on a widget, it uses the provider's active design.
+
+```ts
+type DesignMode =
+  | 'aurora'      // luminous ethereal
+  | 'foundry'     // warm volumetric industrial
+  | 'tide'        // fluid organic wave
+  | 'void'        // minimal negative space
+  | 'mineral'     // faceted crystal gem
+  | 'meridian'    // hairline geometric
+  | 'signal'      // pixel/blocky lo-fi
+  | 'paper'       // flat ink editorial
+  | 'sundial'     // roman/classical carved
+  | 'parchment';  // document strokes
+```
+
+---
+
+## Positioning
+
+```tsx
+<SolarWidget />                                                         // inline (default)
+<SolarWidget position="bottom-right" />                                 // fixed to viewport
+<SolarWidget position="bottom-right" expandDirection="top-left" />      // with expand direction
+```
+
+Supported positions: `top-left` `top-center` `top-right` `center-left` `center` `center-right` `bottom-left` `bottom-center` `bottom-right` `inline`
+
+---
+
+## Weather
+
+```tsx
+<SolarWidget showWeather />
+
+// Force a category for preview
+<SolarWidget showWeather weatherCategoryOverride="thunder" />
+```
+
+Powered by [Open-Meteo](https://open-meteo.com/) — free, no API key. Available categories: `clear` `partly-cloudy` `overcast` `fog` `drizzle` `rain` `heavy-rain` `snow` `heavy-snow` `thunder`
+
+---
+
+## Phase & Time Overrides
+
+```tsx
+// Force a discrete phase
+<SolarWidget phaseOverride="sunset" />
+
+// Simulate a specific time (with blend)
+const preview = new Date();
+preview.setHours(6, 45, 0, 0);
+<SolarWidget simulatedDate={preview} />
+```
+
+Use `simulatedDate` for realistic continuous previews. Use `phaseOverride` for simple hard overrides.
+
+---
+
+## Custom Palettes
+
+```tsx
+<SolarWidget
+  customPalettes={{
+    dawn:   { bg: ['#20122a', '#7f3b5d', '#f5a66e'] },
+    sunset: { bg: ['#2e0f18', '#b84a3d', '#ffbe7a'] },
+  }}
+/>
+```
+
+---
+
+## SolarDevTools
+
+A dev-only bottom-fixed pill for scrubbing through the day. Imported from a dedicated subpath — never included in production bundles unless explicitly imported.
+
+```tsx
+import { SolarDevTools } from '@qodin-co/sol/devtools';
+
+// Vite
+{import.meta.env.DEV && <SolarDevTools />}
+
+// Next.js
+{process.env.NODE_ENV === 'development' && <SolarDevTools />}
+```
+
+### Full example
+
+```tsx
+import '@qodin-co/sol/styles.css';
+import { SolarThemeProvider, SolarWidget } from '@qodin-co/sol';
+import { SolarDevTools } from '@qodin-co/sol/devtools';
+
+export default function Demo() {
+  return (
+    <SolarThemeProvider initialDesign="foundry">
+      <SolarWidget showWeather showFlag />
+      {process.env.NODE_ENV === 'development' && (
+        <SolarDevTools position="bottom-center" />
+      )}
+    </SolarThemeProvider>
+  );
+}
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `defaultOpen` | `boolean` | `false` | Start expanded |
+| `position` | `'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-center'` | Pill position |
+| `enabled` | `boolean` | `true` | Programmatic enable/disable |
+
+---
+
+## useSolarTheme
+
+```tsx
+import { useSolarTheme } from '@qodin-co/sol';
+
+function DebugPanel() {
+  const { phase, timezone, latitude, longitude, design } = useSolarTheme();
+  return (
+    <pre>{JSON.stringify({ phase, timezone, latitude, longitude, design }, null, 2)}</pre>
+  );
+}
+```
+
+### Return shape
+
+| Property | Type | Description |
+|---|---|---|
+| `phase` | `SolarPhase` | Current active phase |
+| `blend` | `SolarBlend` | Phase blend state (phase, nextPhase, t) |
+| `isDaytime` | `boolean` | Whether the sun is above the horizon |
+| `brightness` | `number` | 0–1 brightness value |
+| `mode` | `'light' \| 'dim' \| 'dark'` | Current light mode |
+| `accentColor` | `string` | Active accent hex |
+| `timezone` | `string \| null` | Resolved timezone |
+| `latitude` | `number \| null` | Resolved latitude |
+| `longitude` | `number \| null` | Resolved longitude |
+| `coordsReady` | `boolean` | Whether coordinates have resolved |
+| `design` | `DesignMode` | Active skin name |
+| `activeSkin` | `SkinDefinition` | Full skin definition object |
+| `setOverridePhase` | `(phase \| null) => void` | Set/clear phase override |
+| `setDesign` | `(skin: DesignMode) => void` | Change active skin |
+
+---
+
+## Multiple Widgets
+
+```tsx
+<SolarThemeProvider initialDesign="foundry">
+  <SolarWidget showWeather />
+  <CompactWidget design="signal" />
+  <SolarWidget />
+</SolarThemeProvider>
+```
+
+Each widget can have its own design. The provider manages shared solar state.
+
+---
+
+## TypeScript
+
+```ts
+import type {
+  DesignMode,
+  SolarPhase,
+  SolarBlend,
+  WeatherCategory,
+  ExpandDirection,
+  WidgetSize,
+  CompactSize,
+  SkinDefinition,
+  WidgetPalette,
+  SolarTheme,
+} from '@qodin-co/sol';
+```
+
+---
+
+## SSR / Hydration Notes
+
+Sol is client-aware and uses browser APIs for geolocation, timezone, and storage. The provider falls back safely when coordinates are not yet resolved. Use the `ClientOnly` wrapper if you encounter hydration mismatches in SSR frameworks.
+
+---
+
+## What's Included
+
+| | |
+|---|---|
+| ✅ | Full widget + compact widget |
+| ✅ | 10 skins with full + compact variants |
+| ✅ | Solar math (NOAA equations, no external API) |
+| ✅ | Timezone fallback logic |
+| ✅ | Optional live weather (Open-Meteo) |
+| ✅ | Skin-aware country flags |
+| ✅ | Dev timeline scrubber |
+| ✅ | Compiled CSS (no Tailwind required) |
+| ❌ | No solar API key needed |
+| ❌ | No weather API key needed |
+| ❌ | No Tailwind in your app |
+| ❌ | No geolocation permission required |
+
+---
+
+## Coming Soon
+
+**SOL** website is launching soon — a dedicated site for Sol with full documentation, live skin previews, and a playground to explore every phase and skin combination.
+
+Sol is actively being developed. Things in progress:
+
+- **Seasonal theme system** — 4 seasons (Summer, Autumn, Winter, Spring) that blend automatically with the existing 9-phase system, computed from date and location with no configuration required
+- More skins
+- Vue and Svelte adapters
+- Deep token override system
+
+Follow the repo or watch releases to stay updated.
+
+---
+
+<div align="center">
+
+MIT © [qodin](https://github.com/qodin-co)
+
 </div>