skytone 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- Sun and moon positions, sunrise and sunset, polar day and night.
+- Palettes keyed to the sun's altitude, with separate morning and evening tints.
+- A watercolour plate painter: graded washes, sweeps, wisps, low-sun curtains, rain, snow, fog, storms and land at dusk.
+- `SkyRenderer`: WebGL2 with cubic B-spline upsampling, watercolour texture, easing between plates, offscreen pausing and context-loss recovery.
+- Open-Meteo forecast and place search, with interpolation between hours.
+- PNG, JPEG and SVG stills.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Skytone contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# skytone
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A living watercolour sky for any interface. Give it a place and a moment, and it paints the sky there: the sun and moon where they really are, the weather from the live forecast, rendered as soft washes by a small WebGL2 renderer. No dependencies.
+
+It's the engine behind [Skytone Studio](https://skytone.site).
+
+```bash
+npm install skytone
+```
+
+## Quick start
+
+```ts
+import { SkyRenderer, skyAt, presetConditions } from 'skytone';
+
+const canvas = document.querySelector('canvas')!;
+const sky = new SkyRenderer(canvas); // sizes itself to the canvas and pauses offscreen
+
+const { plate } = skyAt({
+  latitude: 19.08,
+  longitude: 72.88,
+  time: Date.now(),
+  conditions: presetConditions('partly'),
+});
+
+sky.setPlate(plate);
+sky.start();
+```
+
+Give the canvas a size with CSS (`width: 100%; height: 100%`). The sky covers it at any aspect ratio.
+
+## With the live forecast
+
+```ts
+import { SkyRenderer, conditionsAt, fetchForecast, skyAt } from 'skytone';
+
+const latitude = 51.51, longitude = -0.13;
+const sky = new SkyRenderer(canvas);
+const forecast = await fetchForecast(latitude, longitude); // Open-Meteo, no key needed
+
+function paint() {
+  const { conditions } = conditionsAt(forecast, Date.now());
+  const { plate } = skyAt({ latitude, longitude, time: Date.now(), conditions });
+  sky.setPlate(plate, { storm: conditions.storm }); // changes ease in over a second
+}
+
+paint();
+sky.start();
+setInterval(paint, 60_000);
+```
+
+## Text on top
+
+`skyAt` also says which text colour reads best on the current sky:
+
+```ts
+const { foreground } = skyAt({ latitude, longitude, time: Date.now(), conditions });
+document.body.dataset.foreground = foreground; // 'light' or 'dark'
+```
+
+## React
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { SkyRenderer, type Plate } from 'skytone';
+
+export function Sky({ plate }: { plate: Plate }) {
+  const ref = useRef<HTMLCanvasElement>(null);
+  const sky = useRef<SkyRenderer | null>(null);
+
+  useEffect(() => {
+    sky.current = new SkyRenderer(ref.current!);
+    sky.current.start();
+    return () => sky.current?.destroy();
+  }, []);
+
+  useEffect(() => sky.current?.setPlate(plate), [plate]);
+
+  return <canvas ref={ref} style={{ width: '100%', height: '100%' }} aria-hidden />;
+}
+```
+
+## How it works
+
+1. **Sun and moon.** Positions come from low-precision astronomical formulas. The tests check sunrise and sunset against published times to within three minutes, including polar night.
+2. **A plate.** The scene is painted into an 80×45 colour grid, the way a watercolourist paints a sky: a graded wash, then soft brush strokes laid wet into it. The palette follows the sun's *altitude*, not the clock, so 6 pm in Oslo in December and 6 pm in Mumbai in June are different skies. Clouds come in as broad sweeps, high wisps, and at low sun, curtains rising from the horizon. Rain, snow, fog, storms and land at dusk are layered on top.
+3. **The renderer.** A WebGL2 shader upsamples the plate with a cubic B-spline, which never draws an edge. It adds a gentle current, faint smoky texture and paper grain, and eases between plates so the sky morphs instead of cutting.
+
+Painting a plate is pure and deterministic: the same place, time, conditions and seed always give the same sky.
+
+## API
+
+### Painting a sky
+
+| Export | What it does |
+| --- | --- |
+| `skyAt(options, out?)` | Paints the sky. Returns `{ plate, scene, phase, foreground }`. |
+| `SkyOptions` | `{ latitude, longitude, time, conditions, seed?, viewAzimuth? }`. `time` is epoch ms. `seed` varies the composition (defaults to one per place). `viewAzimuth` is the compass direction the view faces (defaults to facing the equator). |
+| `sceneFor(options)` | The sun, moon and conditions for a moment, without painting. |
+| `paintPlate(scene, out?)` | Paints a scene into a plate. Pass `out` to reuse memory. |
+| `phaseOf(altitude)` | `'night' \| 'astronomical' \| 'nautical' \| 'civil' \| 'golden' \| 'day'`. |
+| `seedFor(latitude, longitude)` | The default seed for a place. |
+| `createPlate()`, `PLATE_W`, `PLATE_H` | A plate is a `Float32Array` of sRGB values, row 0 at the top. |
+| `plateAverage(plate, v0?, v1?)` | Average colour, optionally of a horizontal band (0 bottom, 1 top). |
+| `foregroundFor(plate)` | `'light'` or `'dark'` text for this sky. |
+
+### Rendering
+
+`new SkyRenderer(canvas, options?)`
+
+| Option | Default | |
+| --- | --- | --- |
+| `renderScale` | `0.5` | Resolution relative to CSS pixels × devicePixelRatio. The sky is soft, so half resolution looks the same and costs a quarter. |
+| `size` | | A fixed `{ width, height }` drawing buffer (for exports). Turns off automatic resizing. |
+| `look` | `DEFAULT_LOOK` | Partial `Look`. |
+| `preserveDrawingBuffer` | `false` | Keep frames readable (for exports). |
+
+| Method | |
+| --- | --- |
+| `setPlate(plate, { instant?, storm? })` | Shows a plate. Changes ease in; large jumps soften briefly. `storm` (0..1) adds distant flashes. |
+| `setLook(look)` | `{ watercolor, motion, softness, grain }`, each 0..1 (`softness` 0..2). |
+| `start()`, `stop()` | The animation loop. It also pauses on its own when the canvas is offscreen or the tab is hidden. |
+| `renderFrame(seconds)` | Draws one frame at an explicit time (exports, video). |
+| `setSize(width, height)` | Sets the drawing buffer when `size` was given. |
+| `destroy({ releaseContext? })` | Frees GPU resources. Pass `releaseContext: true` for a throwaway canvas. |
+
+`SkyRenderer` needs WebGL2, which every current browser has. It recovers from a lost GPU context.
+
+### Weather
+
+| Export | |
+| --- | --- |
+| `presetConditions(preset, intensity?)` | Conditions without a network call. Presets: `clear`, `partly`, `cloudy`, `overcast`, `rain`, `snow`, `fog`, `storm`. `intensity` is 0..1. |
+| `fetchForecast(latitude, longitude, options?)` | Hourly forecast from Open-Meteo: the past 7 days and the next 16. |
+| `conditionsAt(forecast, time)` | `{ conditions, known }`, interpolated between hours. Outside the forecast it returns a typical sky with `known: false`. |
+| `searchPlaces(query, options?)` | Place search (Open-Meteo geocoding). Returns `{ name, region, country, latitude, longitude, timezone }[]`. |
+| `placeQueryFromTimezone(tz?)` | A city name from the device timezone, for a first guess with no permission prompt. |
+| `lerpConditions(a, b, t)`, `describe(conditions)`, `CONDITION_PRESETS` | Helpers. |
+
+`Conditions` is `{ cloud, cloudLow, cloudHigh, rain, snow, fog, storm, windSpeed, windDirection, temperature }`, each normalised to 0..1 except wind (m/s, degrees) and temperature (°C or `null`).
+
+The forecast functions accept `{ baseUrl, geocodingUrl, apiKey, signal }` to point at Open-Meteo's commercial endpoint or cancel a request.
+
+### Sun and moon
+
+| Export | |
+| --- | --- |
+| `sunPosition(time, latitude, longitude)` | `{ altitude, azimuth, rising }` in degrees. Azimuth is clockwise from north. |
+| `moonPosition(time, latitude, longitude)` | `{ altitude, azimuth, fraction }`, where `fraction` is the illuminated part (0 new, 1 full). |
+| `sunEvents(dayStart, latitude, longitude)` | `{ sunrise, sunset, always }` within 24 hours of `dayStart`. `always` is `'up'` or `'down'` for polar day and night. |
+
+### Images
+
+| Export | |
+| --- | --- |
+| `renderStill(plate, { width, height, look?, time? })` | Renders a plate at full resolution into a new canvas. |
+| `stillBlob(plate, options, 'image/png' \| 'image/jpeg', quality?)` | The same, as a `Blob`. |
+| `plateToSVG(plate, width, height)` | A resolution-independent SVG of the washes (no paper texture or grain). |
+
+## Where it runs
+
+- **Browsers:** everything. The renderer and image functions need a DOM and WebGL2.
+- **Node 18+, Deno, Bun, workers:** the sky model (`skyAt`, `paintPlate`, sun, moon, palettes) and the weather functions. These need no DOM, so you can paint plates on a server and render them on the client.
+
+## Data and credits
+
+- Weather and place search use [Open-Meteo](https://open-meteo.com/), whose data is licensed CC BY 4.0. Credit Open-Meteo wherever you show its weather. Its free API is for non-commercial use; commercial apps need an Open-Meteo plan (`baseUrl` and `apiKey`) or their own provider, which works with `presetConditions` or your own `Conditions`.
+- The sun and moon formulas follow those used by [SunCalc](https://github.com/mourner/suncalc) by Vladimir Agafonkin.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+interface BodyPosition {
+    /** Degrees above the horizon. Negative below. */
+    altitude: number;
+    /** Degrees clockwise from north. */
+    azimuth: number;
+}
+interface SunPosition extends BodyPosition {
+    /** True while the sun climbs (morning). */
+    rising: boolean;
+}
+interface MoonPosition extends BodyPosition {
+    /** Illuminated fraction, 0 (new) to 1 (full). */
+    fraction: number;
+}
+declare function sunPosition(time: number, lat: number, lon: number): SunPosition;
+declare function moonPosition(time: number, lat: number, lon: number): MoonPosition;
+interface SunEvents {
+    sunrise: number | null;
+    sunset: number | null;
+    /** Polar day or night: the sun never crosses the horizon in this window. */
+    always: 'up' | 'down' | null;
+}
+/** Sunrise and sunset inside [start, start + 24h), found by scanning altitude. */
+declare function sunEvents(start: number, lat: number, lon: number): SunEvents;
+
+type RGB = [number, number, number];
+declare function rgbToOklab([r, g, b]: RGB): RGB;
+declare function oklabToRgb([L, a, b]: RGB): RGB;
+/** Perceptual blend. Sunsets pass through pink, not grey. */
+declare function mixOklab(a: RGB, b: RGB, t: number): RGB;
+declare const luminance: (c: RGB) => number;
+declare const toHex: (c: RGB) => string;
+
+interface Palette {
+    zenith: RGB;
+    mid: RGB;
+    horizon: RGB;
+    /** Deeper sky pooled at the top of the frame. */
+    deep: RGB;
+    /** Pale sky showing between masses. */
+    highlight: RGB;
+    /** The lit side of cloud. */
+    light: RGB;
+    /** The shaded side of cloud. */
+    shadow: RGB;
+    /** Warm dust near the horizon. */
+    warm: RGB;
+    /** Land silhouette at dusk and night. */
+    ground: RGB;
+    /** Light around the sun. */
+    glow: RGB;
+}
+declare function paletteAt(altitude: number, rising?: boolean): Palette;
+
+/** Everything the painter needs to know about the weather, normalised to 0..1. */
+interface Conditions {
+    /** Total cloud cover. */
+    cloud: number;
+    /** Low cloud: heavy masses near the horizon. */
+    cloudLow: number;
+    /** High cloud: thin wisps up top. */
+    cloudHigh: number;
+    rain: number;
+    snow: number;
+    fog: number;
+    storm: number;
+    /** Metres per second. */
+    windSpeed: number;
+    /** Degrees the wind blows *from*, clockwise from north. */
+    windDirection: number;
+    /** Celsius, when known. */
+    temperature: number | null;
+}
+type ConditionPreset = 'clear' | 'partly' | 'cloudy' | 'overcast' | 'rain' | 'snow' | 'fog' | 'storm';
+declare const CONDITION_PRESETS: {
+    id: ConditionPreset;
+    name: string;
+}[];
+/** A preset at a given intensity (0..1). Intensity 0.5 is the typical case. */
+declare function presetConditions(preset: ConditionPreset, intensity?: number): Conditions;
+declare function lerpConditions(a: Conditions, b: Conditions, t: number): Conditions;
+/** A believable sky for dates outside any forecast: some cloud, nothing falling. */
+declare const SEASONAL_CONDITIONS: Conditions;
+/** Which preset best describes some conditions (for labels). */
+declare function describe(c: Conditions): ConditionPreset;
+
+interface Place {
+    name: string;
+    region?: string;
+    country?: string;
+    latitude: number;
+    longitude: number;
+    /** IANA zone, e.g. "Asia/Kolkata". */
+    timezone: string;
+}
+interface Forecast {
+    latitude: number;
+    longitude: number;
+    timezone: string;
+    /** Hour starts, epoch ms. */
+    times: number[];
+    hours: Conditions[];
+    /** Raw readings for display, aligned with `times`. */
+    readings: {
+        cloudCover: number;
+        precipitation: number;
+        snowfall: number;
+        code: number;
+        windKmh: number;
+        temperature: number;
+    }[];
+}
+interface OpenMeteoOptions {
+    /** Override for the commercial endpoint, e.g. https://customer-api.open-meteo.com */
+    baseUrl?: string;
+    geocodingUrl?: string;
+    apiKey?: string;
+    pastDays?: number;
+    forecastDays?: number;
+    signal?: AbortSignal;
+}
+/** WMO weather code + readings → normalised conditions. */
+declare function conditionsFromReading(r: {
+    cloud: number;
+    low: number;
+    high: number;
+    precip: number;
+    rain: number;
+    snowfall: number;
+    code: number;
+    visibility: number;
+    wind: number;
+    windDir: number;
+    temp: number | null;
+}): Conditions;
+declare function fetchForecast(latitude: number, longitude: number, opts?: OpenMeteoOptions): Promise<Forecast>;
+/** Conditions at any instant: interpolated inside the forecast, seasonal outside it. */
+declare function conditionsAt(forecast: Forecast | null, time: number): {
+    conditions: Conditions;
+    known: boolean;
+    index: number;
+};
+declare function searchPlaces(query: string, opts?: OpenMeteoOptions): Promise<Place[]>;
+/**
+ * A place guessed from the device timezone alone: no permission prompt, no network.
+ * "Asia/Kolkata" → search "Kolkata". Callers refine it with geolocation if granted.
+ */
+declare function placeQueryFromTimezone(tz?: string): string | null;
+
+/**
+ * A plate is the whole sky as a small colour grid, painted the way a watercolourist paints
+ * a sky: a graded wash, then soft brush strokes laid wet into it. The renderer upsamples it
+ * with a smooth cubic filter. Row 0 is the top of the sky. Values are sRGB 0..255.
+ */
+declare const PLATE_W = 80;
+declare const PLATE_H = 45;
+type Plate = Float32Array;
+declare const createPlate: () => Plate;
+interface SceneInput {
+    /** Epoch ms. Drives the slow drift of cloud across the frame. */
+    time: number;
+    sun: SunPosition;
+    moon: MoonPosition;
+    conditions: Conditions;
+    /** Compass direction the view faces, degrees. */
+    viewAzimuth: number;
+    /** Varies the composition. Same seed, same sky. */
+    seed: number;
+}
+/** Paint a scene into `out` (or a new plate). Pure: same input, same plate. */
+declare function paintPlate(scene: SceneInput, out?: Plate): Plate;
+/** Average colour of the plate (or a horizontal band of it, v from 0 bottom to 1 top). */
+declare function plateAverage(plate: Plate, v0?: number, v1?: number): RGB;
+/** Light or dark text reads best on this sky. */
+declare function foregroundFor(plate: Plate): 'light' | 'dark';
+
+type Phase = 'night' | 'astronomical' | 'nautical' | 'civil' | 'golden' | 'day';
+declare function phaseOf(altitude: number): Phase;
+/** A stable seed for a place, so a city keeps its own character. */
+declare function seedFor(latitude: number, longitude: number): number;
+interface SkyOptions {
+    latitude: number;
+    longitude: number;
+    time: number;
+    conditions: Conditions;
+    seed?: number;
+    /** Defaults to facing the equator, so the sun arcs left to right. */
+    viewAzimuth?: number;
+}
+declare function sceneFor(o: SkyOptions): SceneInput;
+interface SkyState {
+    scene: SceneInput;
+    plate: Plate;
+    phase: Phase;
+    foreground: 'light' | 'dark';
+}
+declare function skyAt(o: SkyOptions, out?: Plate): SkyState;
+
+interface Look {
+    /** Speed of the slow ambient drift. 0 holds the sky still. */
+    motion: number;
+    /** Extra softness, in plate cells. */
+    softness: number;
+    /** Film grain, 0..1. */
+    grain: number;
+    /** Watercolour, 0..1: flowing wet-in-wet edges, pigment pooling and paper. 0 is a pure colour field. */
+    watercolor: number;
+}
+declare const DEFAULT_LOOK: Look;
+interface RendererOptions {
+    /** Resolution relative to CSS pixels × devicePixelRatio. The sky is soft, so 0.5 looks identical. */
+    renderScale?: number;
+    /** Fixed drawing-buffer size (exports). Disables automatic resizing. */
+    size?: {
+        width: number;
+        height: number;
+    };
+    look?: Partial<Look>;
+    /** Keep the drawing buffer so frames can be read back (exports). */
+    preserveDrawingBuffer?: boolean;
+}
+declare class SkyRenderer {
+    readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+    private gl;
+    private u;
+    private tex;
+    private program;
+    private buffer;
+    private shown;
+    private target;
+    private rgba;
+    private hasPlate;
+    private morph;
+    private storm;
+    private look;
+    private opts;
+    private raf;
+    private last;
+    private clock;
+    private visible;
+    private running;
+    private observers;
+    private lost;
+    private onVisibility;
+    constructor(canvas: HTMLCanvasElement | OffscreenCanvas, opts?: RendererOptions);
+    private init;
+    private onLost;
+    private onRestored;
+    private observe;
+    private fit;
+    setSize(width: number, height: number): void;
+    setLook(look: Partial<Look>): void;
+    /** Show a plate. Changes ease in; large jumps soften briefly, the way the sky morphs. */
+    setPlate(plate: Plate, opts?: {
+        instant?: boolean;
+        storm?: number;
+    }): void;
+    private upload;
+    private step;
+    private flash;
+    /** Draw one frame at an explicit time (seconds). Used for exports. */
+    renderFrame(timeSec: number): void;
+    private draw;
+    /** Advance easing toward the target instantly (exports, tests). */
+    settle(): void;
+    start(): void;
+    stop(): void;
+    private wake;
+    /**
+     * Stop and free GPU resources. The canvas keeps its context so a new renderer can reuse it
+     * (React remounts do exactly that). Pass `releaseContext` for throwaway canvases, such as exports.
+     */
+    destroy(opts?: {
+        releaseContext?: boolean;
+    }): void;
+}
+
+interface StillOptions {
+    width: number;
+    height: number;
+    look?: Partial<Look>;
+    storm?: number;
+    /** Seconds on the drift clock. */
+    time?: number;
+}
+/** Render a plate at full resolution into a fresh canvas. */
+declare function renderStill(plate: Plate, o: StillOptions): HTMLCanvasElement;
+declare function stillBlob(plate: Plate, o: StillOptions, type: 'image/png' | 'image/jpeg', quality?: number): Promise<Blob>;
+/**
+ * A resolution-independent SVG: the plate as a grid of colour cells under a Gaussian blur.
+ * Edge cells are repeated outward so the blur never darkens the frame's edges.
+ */
+declare function plateToSVG(plate: Plate, width: number, height: number): string;
+
+export { type BodyPosition, CONDITION_PRESETS, type ConditionPreset, type Conditions, DEFAULT_LOOK, type Forecast, type Look, type MoonPosition, type OpenMeteoOptions, PLATE_H, PLATE_W, type Palette, type Phase, type Place, type Plate, type RGB, type RendererOptions, SEASONAL_CONDITIONS, type SceneInput, type SkyOptions, SkyRenderer, type SkyState, type StillOptions, type SunEvents, type SunPosition, conditionsAt, conditionsFromReading, createPlate, describe, fetchForecast, foregroundFor, lerpConditions, luminance, mixOklab, moonPosition, oklabToRgb, paintPlate, paletteAt, phaseOf, placeQueryFromTimezone, plateAverage, plateToSVG, presetConditions, renderStill, rgbToOklab, sceneFor, searchPlaces, seedFor, skyAt, stillBlob, sunEvents, sunPosition, toHex };