WhatTheStar · /design
compositions› guide

    Guide System

    The lesson shell: a computed viewing night, a step vocabulary wired to the sky engine, and a HUD that admits when a lesson is pointing at nothing.

    The viewing night is computed, not declared

    A lesson used to open on the reader's current real month. Eleven of nineteen lessons therefore had steps pointed at ground, and two showed a green "compatible" badge over a subject six degrees below the horizon, because the check asked about hemisphere, declination and a hand-written list of months and never once asked how high the thing was.

    A lesson now declares a subject. The shell searches forward from today for the first night on which that subject culminates during astronomical darkness at the reader's location, shows that instant, and says so on the intro card. The reader can still choose tonight or name a date; if the subject is not up then, the card gives the real altitude and offers the night that works. The lessons index runs the same solver, so the promise it makes and the night the lesson opens on are the same night by construction.

    One target grammar

    Every verb takes a GuideTarget: a string resolved as star proper name, Bayer/Flamsteed designation, Messier/NGC id, deep-sky common name, solar-system body, or IAU three-letter region code — or a [ra, dec] pair. Resolution happens in one function, so a name that means nothing fails in one place, and it fails visibly: the HUD prints the fault instead of the object silently vanishing.

    <Guide>

    PropTypeMeaning
    title / module / description string Intro card copy. `title` accepts HTML.
    slug string Progress key, and the key this lesson's viewing choices are stored under.
    subject GuideTarget What the lesson is about: "M31", "Dubhe", "Jupiter", "ORI" or [ra, dec]. The guide opens on the night this is highest during astronomical darkness. Omit it and the lesson is about tonight.
    subjectLabel string Prose name for the subject. Needed whenever `subject` is a coordinate pair.
    requires { maxBortle?: number } Sky darkness only. Geometry is computed, not declared.
    defaultLocation [lat, lon] The site the lesson was written from; the fallback when the reader has saved none.
    defaultHour 0–23 The hour a subject-less lesson is shown at, and the seed for the date picker.
    sources { label, href? }[] Required. A lesson that states a number says where the number came from.
    initialRa / initialDec / initialFov number Where the camera starts, before step one.

    <Step>

    PropTypeMeaning
    panTo GuideTarget Aim. A name is resolved at the step's instant, which is the only way to aim at a planet.
    lookAtAltAz [az, alt] Aim by bearing. Turns the horizon on by default.
    zoom number Field of view in degrees.
    frame string[] Fit a group of catalogue stars. Names it cannot place, and groups wider than the projection, are reported on screen instead of cropped.
    highlight / clearHighlights string / boolean Constellation figure, and whether to drop the previous ones.
    measure [GuideTarget, GuideTarget] Great-circle separation, captioned in degrees and in hand-widths.
    circle { at, radiusDeg, label? } A ring of stated angular radius: an eyepiece field, a search area.
    callout { at, text } A line of text pinned to a place on the sky.
    path GuideTarget[] A polyline through the targets, in order.
    body string Select and name a solar-system body at this step's instant.
    dso string Select and name a deep-sky object. "M31", "NGC 869", "Andromeda Galaxy".
    showData ('altitude'|'azimuth'|'time'|'date')[] Live numbers for the step's subject in the HUD, updating through a time-lapse. Turns itself on when a marked body or DSO is below the horizon.
    timeLapse { hours, duration, track? } `track` defaults false: a time-lapse shows the sky turning, and locking onto the subject cancels that.
    locationSequence { lat, lon, label }[] Walk the observer across the Earth.
    horizon / cardinals boolean `horizon` defaults true for any step with `timeLapse` or `lookAtAltAz`.
    grid 'equatorial'|'altaz'|'ecliptic' One overlay at a time; every other step is guaranteed not to inherit it.
    focus 'none'|'soft'|'strong' Dimming. Auto-detected from whether the step marks anything.

    Plus the two annotation children, unchanged: <StarLabel star detail /> and <Arrow from to extend dashed label />.

    Removed

    • requires.months — nineteen hand-maintained season lists, several of them wrong. Replaced by the computed night.
    • requires.hemisphere and requires.minDec — flags that approximated an altitude the guide now states exactly.
    • The single global whatthestar:guide-view key — one lesson's viewing night used to be all nineteen lessons' viewing night.
    • Automatic camera tracking during a time-lapse, which cancelled the rotation the time-lapse existed to show.

    Live examples

    Big Dipper → Orion → Andromeda Galaxy → Pleiades →

    Guides do not render standalone: they need MapLayout for the sky canvas, and GuideDirector drives the steps. Files live in src/design/compositions/guide/, with the night solver in src/Engine/GuideSubject.ts.