astrolabe/SOUL.md

# Astrolabe — What This Project Is About

## The Problem

People who work with [Vega-Lite](https://vega.github.io/vega-lite/) directly — analysts,
educators, chart authors — don't have a fast, private place to *keep* their charts. The
official Vega-Lite editor is great for a single spec in a tab, but it forgets everything
when you close it. Notebooks bury charts in code. BI tools hide the spec behind a GUI and
lock you into an account.

Astrolabe fills this gap: **a local-first workspace where you author Vega-Lite specs as
JSON, see them render live, and keep a personal, searchable library of them — with no
account, no server, and full offline use.**

## The Core Idea

The central artifact is the **snippet**: a saved Vega-Lite specification plus metadata.
Everything else — the editor, the live preview, the dataset library, the chart builder —
exists to author, organize, and reuse snippets. Astrolabe does not abstract Vega-Lite
away; a snippet *is* a Vega-Lite spec. The chart builder offers a no-JSON on-ramp, but the
JSON is always the source of truth and always editable.

Reusable **datasets** are stored once and referenced by name from many snippets, so the
data lives in one place and the specs stay lean.

## Core Values

### 1. Local-Only by Default
Everything runs in the browser. Snippets, datasets, and settings never leave the machine.
No accounts, no uploads, no tracking. The only outbound requests are user-created
URL-dataset fetches.

### 2. Vega-Lite Native, Not Vega-Lite Hidden
The product domain *is* Vega-Lite. We validate, render, and reason about specs as
Vega-Lite, and we surface its real vocabulary (marks, encodings, field types). We don't
invent a parallel chart abstraction. The chart builder is an on-ramp, not a replacement
for the spec.

### 3. Experiment Safely
A snippet carries a stable **published** spec and an editable **draft**. You can tinker
freely without losing a known-good version. Auto-save protects in-progress work; publish
promotes it deliberately.

### 4. Beginner On-Ramp, Power-User Ceiling
The chart builder lets someone produce a chart without writing JSON. The editor — with
schema-aware autocomplete and live validation — lets a power user do anything Vega-Lite
can. Neither caps the other.

### 5. Own Your Data
Fully local and offline-capable, with import/export for backup and transfer. Your library
is a file you control, not a row in someone's database.

### 6. Predictable, Not Clever
When a behavior could go several ways, pick the one closest to the user's existing mental
model (the Vega-Lite editor, JSON tooling, file-based apps). Least surprise beats most
clever.

## What We're Not

- **Not a BI/dashboarding tool.** A snippet is *one* visualization, not a composed report
  with cross-filters and layout. Dashboards are a different product.
- **Not a data-wrangling tool.** Datasets are stored and referenced, not cleaned or
  transformed. (That's [Syto](https://github.com/) territory — Astrolabe's sibling in
  architecture and quality bar, but a separate product with separate goals.)
- **Not a collaboration platform.** No multi-user, no sync, no comments. Import/export
  moves data between machines.
- **Not a server app.** No backend, no rendering service, no account system.

## Technical Philosophy

### Spec-Driven, Clean Implementation
The behavioral contract lives in `docs/spec/`. Astrolabe is a deliberate rebuild on a
robust architecture (adapted from Syto): we implement *to the spec*, not by porting old
code. When the spec and convenience conflict, the spec wins or the spec changes — never
silent drift.

### Portable Core, Thin Browser Shell
`src/core/` is pure and portable — no browser APIs, no UI framework. Spec operations
(detection, profiling, reference resolution, fit transforms, validation, import
normalization) live there and are tested hardest. The UI is a thin, replaceable shell over
that core.

### Leverage Existing Libraries
Vega-Lite renders. Monaco edits. vega-embed mounts charts. React + Zustand drive the UI.
We wrap these with thin integration layers rather than reinventing them. Custom code
focuses on what's unique to Astrolabe: the snippet/dataset model, the rendering contract,
and the workspace that ties it together.

### No Parallel Systems
Each fact lives in one place. A snippet↔dataset link, a setting, a schema — one source of
truth, others derived. If you're writing the same logic twice, one should import or be
generated from the other.

### Test the Core, Trust the UI
High coverage on the portable engine (where a bug corrupts data or breaks rendering);
lighter coverage on components (where a bug is a cosmetic annoyance).

## The Name

An **astrolabe** is an ancient instrument for locating and predicting the positions of
stars — a tool for finding your way by the sky. The app helps you find your way through a
library of visualizations: keep them, locate them, and see where each one points.