@yuzuwoeser/astr3 0.0.0-stage → 0.1.1

package/AGENTS.md

@@ -0,0 +1,105 @@
+# Working on ASTR3
+
+These instructions apply to the entire repository. For agents integrating the
+library into another application, start with [docs/agent-integration.md](docs/agent-integration.md).
+
+Use **ASTR3** for the display name and project-name prose. The npm package and
+its imports use `@yuzuwoeser/astr3`. Other technical identifiers such as URLs, CSS
+classes and JavaScript globals use `astr3`.
+The website wordmark is live text in Righteous Regular (400), with mint, sky blue,
+lavender, coral and gold characters on a dark background. Match the palette in
+`site/public/brand/palette.json`; keep the locally bundled font and its SIL OFL
+copyright/license notices together.
+
+## Setup and checks
+
+Use Node.js 24 LTS (supported minimum: 22.12.0) and npm. From the repository root:
+
+```sh
+npm ci
+npm exec playwright -- install chromium
+npm run dev
+```
+
+The website URL is printed by Vite. Development-browser tests use port 4173; Pages
+production smoke tests use port 4174. Stop unrelated servers on those ports before
+running the corresponding suite. In Linux CI, install Chromium with
+`npm exec playwright -- install --with-deps chromium`.
+
+```sh
+npm run typecheck      # TypeScript, including website, playground and tests
+npm test              # Unit tests and independent numerical reference fixtures
+npm run check         # Types, unit/reference tests, both builds, packed consumer
+npm run test:browser  # Chromium desktop and mobile touch emulation
+npm run test:pages    # Build and smoke-test the production website beneath /astr3/
+npm run format:check
+```
+
+Run focused checks while editing. Before completing a change, run the checks
+appropriate to it. Public API, calculation, layout, picking, accessibility, and
+lifecycle changes need their relevant tests. Renderer or website/example changes
+also need browser validation. A release needs the full sequence in
+[docs/releasing.md](docs/releasing.md). Browser tests do not run inside `npm run check`.
+
+## Where to work
+
+| Path                                                         | Responsibility                                                                  |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `src/model/`                                                 | Headless types, validation, aspects, houses, relationships, transit composition |
+| `src/ephemeris/`                                             | Optional Astronomy Engine adapter, node and house calculations                  |
+| `src/renderer.ts`                                            | Three.js wheel, HTML labels/accessibility, events, DOM/GPU lifecycle            |
+| `src/transit-renderer.ts`                                    | Source-qualified transit API over the shared renderer                           |
+| `src/transit-animation.ts`, `src/transit-sampling.ts`        | Transit animation lifecycle, sampling and cancellation                          |
+| `src/wheel-drawing.ts`, `src/chart-export.ts`                | Shared drawing description and browser SVG/PNG export                           |
+| `src/wheel-geometry.ts`                                      | Default/alternative ring geometry, source bands and annular house sectors       |
+| `src/layout.ts`, `src/label-packing.ts`, `src/chart-text.ts` | Exact projection, bounded label placement, zoom-aware typography                |
+| `src/picking.ts`                                             | Screen-space targets and overlapping selection candidates                       |
+| `site/`                                                      | Project website, generated navigation, branding and Pages configuration         |
+| `examples/`                                                  | Runnable playground, framework examples and backend integration recipes         |
+| `tests/unit/`, `tests/browser/`, `tests/fixtures/`           | Behavioral tests and public/synthetic reference data                            |
+| `scripts/`                                                   | Builds and package consumer validation                                          |
+| `docs/`                                                      | Public contracts, integration and calculation explanations                      |
+
+## Contracts to preserve
+
+- `@yuzuwoeser/astr3/model` must import no DOM, Three.js, or ephemeris code. Importing the
+  main entry must remain SSR-safe; mounting needs a browser and WebGL 2.
+- Use degrees for positions and orbs. Keep exact astronomical positions separate
+  from displaced labels. Never move a longitude to solve a visual collision.
+- Preserve stable IDs. Transit selections require `chart: 'natal' | 'transit'`,
+  or `chart: 'cross'` for cross aspects. Never expose internal scoped renderer IDs.
+- Unknown birth time must not invent houses or axes. Actual cusps may be unequal.
+  AC/MC bodies and independently supplied angles must agree when both are used.
+- Omitted aspects calculate; supplied `[]` means none. Supplied aspects remain
+  authoritative across orb changes, but disabled types are filtered. Keep
+  enablement separate from layer visibility, and retain original inputs for re-enabling.
+- Validation failures must leave the previous chart intact. Models must not
+  mutate caller data. Metadata stays opaque and is retained by reference.
+- Dispose owned DOM/GPU resources, observers, listeners and queued frames. Preserve
+  accessible selection when WebGL is unavailable. Do not add network requests,
+  storage, telemetry or global listeners without a concrete requirement.
+- Do not replace the bounded circular packing solver with greedy placement or
+  unbounded leader lines. Dense views must retain selectable dots/list entries.
+
+Read [docs/api.md](docs/api.md), [docs/transits.md](docs/transits.md), and
+[docs/calculations.md](docs/calculations.md) before changing their contracts.
+Keep application explanations and framework-specific wrappers outside the core.
+
+## Data, documentation and commits
+
+Use invented positions or documented public reference dates/locations in examples,
+tests, screenshots and issues. Do not copy a user's birth data, local paths,
+credentials, logs or agent conversations into tracked files. Numerical reference
+fixtures have independent provenance; do not relabel their input while retaining
+old expected results. Optional Python regeneration is not part of normal setup.
+
+Update affected docs and examples with API/behavior changes. Add an Unreleased
+changelog entry for user-facing changes. Keep `llms.txt` links current. The packed
+consumer check validates exports and declarations; extend it for new entry points.
+Do not hand-edit `dist/`, `site-dist/` or `node_modules/`.
+
+When implementation is authorized, include a local Git commit. Review the final
+diff, run appropriate checks, commit only task changes, preserve unrelated work,
+and use a descriptive message. Report the commit hash and validation results.
+If blocked, explain why and explicitly state that changes remain uncommitted.
+Do not push or publish unless the user asks.

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+User-visible changes are recorded here. The API is experimental until 1.0.
+
+## Unreleased
+
+## 0.1.1
+
+- Wait for npm registry indexing after publication before completing the GitHub
+  Release. Retry transient registry/network failures for up to five minutes,
+  retaining strict package identity and tarball integrity checks.
+- Publish versioned browser, WordPress, and starter bundles through the automated
+  release workflow, alongside the scoped npm package.
+
+## 0.1.0
+
+- Publish the library as `@yuzuwoeser/astr3`, with matching scoped imports and
+  workspace/consumer validation. Keep browser filenames and release asset URLs
+  stable, and default scoped npm publication to public access.
+
+- Add shared release packaging for npm tarballs, versioned browser and WordPress
+  ZIPs, complete framework/server starters, checksums and a source manifest.
+  Add tag-triggered GitHub/npm publishing with exact-artifact rerun guards.
+- Add an installable WordPress chart block and same-post shortcode with natal/
+  transit JSON, local presets, validation feedback and accessible fallback.
+- Lead integration pages with prebuilt installation, minimal usage and cleanup;
+  add a three-route installation chooser and a phased stack coverage roadmap.
+
+- Add syntax highlighting to website source tabs, setup snippets, and JSON
+  previews, with colors for light and dark code panels and locally bundled grammars.
+
+- Add versioned JSON appearance templates for natal and transit charts, synchronous
+  SSR-safe resolvers with field-path errors and independent option copies, and the
+  packaged `@yuzuwoeser/astr3/chart-template.schema.json` schema. Add homepage comparisons,
+  a runnable template example with JSON downloads, and browser/PHP loading guidance.
+
+- Fix GitHub Pages builds on Linux when dependencies ship lowercase license
+  filenames, preserving their actual casing when collecting notices.
+
+- Expand GitHub Pages into the ASTR3 project website with a dedicated playground,
+  generated examples and integration guides for JavaScript, TypeScript, React,
+  Vue.js, Svelte, Angular, PHP, WordPress, and Ruby on Rails.
+- Add a self-hostable browser-module download with optional calculations and
+  SVG/PNG exports. Example code and instructions live in `examples/`; website
+  assets/build configuration move from `demo/` to `site/`.
+
+- Add a GitHub Pages demo build at `/astr3/`, production desktop/mobile smoke
+  tests, and automatic deployment from `main` after checks and history scanning
+  pass. Support manual redeployment while keeping local development at `/`.
+
+- Simplify getting started and complete public API coverage for models, helpers,
+  events, calculation, and transit animation. Separate rendering internals from
+  reference docs and update repository, reporting, and asset-link guidance.
+
+- Adjust demo downloads to 800 × 800 for standard SVG and 1600 × 1600 for large
+  SVG and PNG. Library export defaults remain unchanged.
+
+- Add **Download large SVG** to the demo to retain
+  more labels and degree/retrograde captions in crowded natal and transit charts.
+
+- Add browser SVG and PNG export to natal and transit charts, with outlined text,
+  full/current-view options, transparent backgrounds and demo download actions.
+  Share wheel construction with the interactive renderer and load export fonts
+  only on demand; unsupported custom text reports its missing characters.
+
+- Match the supplied five-color logo palette in the header and footer, with a
+  dark background for contrast. Add reusable outlined SVG logos and palette
+  assets, and display the logo in the README.
+
+- Adopt ASTR3 as the display name and a live-text Righteous Regular (400)
+  wordmark. Bundle the original font locally with its SIL OFL license and retain
+  lowercase `astr3` technical identifiers.
+
+- Add individual celestial-body visibility controls, with separate natal/transit
+  settings, All/None presets, and a `bodyVisibility` API. Hidden bodies and their
+  connectors leave the wheel while their data and accessible selections remain.
+
+- Add opt-in transit time-step animation with direct astronomical samples,
+  adaptive retrograde trajectory resolution, Pause/Resume, reduced-motion support,
+  and a reusable `createTransitAnimation` controller. The demo adds Year stepping
+  with leap-day clamping. Batch wheel drawing to keep animated updates responsive.
+
+- Add `layout: 'default' | 'alternative'` for natal and transit wheels. The
+  alternative places houses outermost, zodiac second and celestial symbols
+  inside, with separate inner aspect anchors and a shared demo selector.
+
+- Validate the packed consumer using local peer archives and an empty npm cache,
+  so fresh CI installations pass without cached registry metadata.
+
+- Prepared the open source repository with public/synthetic fixtures, contributor
+  guidance, agent integration examples and reproducible release privacy checks.
+
+Initial implementation:
+
+- Render Western natal wheels with Three.js and precomputed or locally calculated
+  positions, actual house cusps, AC/MC axes, true lunar nodes and unknown-house support.
+- Select planets, points, houses, aspects and supplied groups directly, with
+  relationship highlighting, details/events and programmatic selection.
+- Explore natal + transit bi-wheels with source-qualified selections and separate
+  natal, cross-chart and transit aspect settings.
+- Configure eleven aspect types, independent enablement and orbs, chart weight,
+  themes, glyphs, layers and line styles.
+- Keep markers at exact longitudes while fitting crowded symbols locally with
+  bounded circular packing, zoom-aware text and selectable cluster badges.
+- Use deterministic conjunction bows, touch/keyboard navigation, an accessible
+  HTML object list and graceful WebGL failure handling.
+- Consume typed ESM entry points for browser rendering, headless models and the
+  optional Astronomy Engine adapter, with lifecycle cleanup and packed-consumer checks.

package/CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing to ASTR3
+
+ASTR3 is an MIT-licensed TypeScript library. Issues and pull requests are welcome.
+The 0.x API may change; discuss a substantial public API change in an issue first.
+Do not include private birth information in reports, screenshots or fixtures.
+
+## Start locally
+
+Use **Node.js 24 LTS**, matching CI. Node 22.12.0 or newer is supported by the
+package. npm and Git are required; `tar`, `zip`, and `unzip` are needed for website
+builds/tests (included on typical macOS/Linux setups). Python and an ephemeris service are not required.
+
+```sh
+git clone https://github.com/yuzuwoeser/astr3.git
+cd astr3
+npm ci
+npm exec playwright -- install chromium
+npm run dev
+```
+
+Open the Vite URL and select **Playground**. Choose a synthetic or public
+calculated preset, then try selecting a body, aspect, house or supplied group. The example application owns
+forms, tooltip text and time controls; the library owns rendering and selection.
+
+## Make and verify a change
+
+Create a branch from `main`. Keep a change focused and preserve existing local
+work. Read [AGENTS.md](AGENTS.md) for source boundaries and invariants, whether you
+work manually or with a coding agent.
+
+```sh
+npm run typecheck
+npm test
+npm run build:site
+npm run typecheck:examples
+npm run test:recipes
+npm run test:package
+npm run test:browser
+npm run format:check
+```
+
+`npm run check` combines types, unit tests, the site/library builds, framework
+checks, recipe syntax checks, and the packed consumer check. The package check
+installs the actual tarball into an isolated consumer and checks ESM imports, SSR-safe imports
+and TypeScript declarations. It packs the installed peers alongside ASTR3 and
+installs those local archives offline with an isolated empty npm cache. It does
+not depend on cached registry metadata. Run `npm ci` first to install the peers.
+
+Browser tests start Vite on **127.0.0.1:4173**, exercising Chromium desktop and
+mobile touch emulation with software WebGL. Stop an unrelated server on that port
+first: local runs may reuse an existing server. Linux needs browser OS packages:
+`npm exec playwright -- install --with-deps chromium`. A desktop-only pinch test
+is intentionally skipped; physical devices, Firefox and Safari are not covered.
+Screenshots and failure traces stay in ignored `test-results/`.
+
+For a focused run, use `npm test -- tests/unit/layout.test.ts` or
+`npm run test:browser -- tests/browser/transits.spec.ts --project=chromium`.
+`npm run format` applies Prettier; review its diff before committing.
+
+Add tests for changed behavior and regressions rather than duplicating the
+implementation. Keep calculation reference tests independent of the algorithm
+under test. Fixtures and optional regeneration provenance are documented in
+[calculations](docs/calculations.md).
+
+The website lives in `site/`; runnable examples and the explorer live in
+`examples/`. See [the examples contributor guide](https://github.com/yuzuwoeser/astr3/blob/main/examples/README.md)
+for the registry and build flow. Framework previews compile against a local npm
+package and load on demand in isolated iframes. Restart `dev` after editing an
+example to rebuild previews. `build:demo` remains an alias for `build:site`.
+Run `npm run test:pages` separately for production routes and examples under
+`/astr3/`; these tests do not run inside `check`.
+
+## Submit a pull request
+
+- Explain the observable problem and resulting behavior. Include a small public
+  or synthetic reproduction for fixes.
+- Document public options, event/data changes, calculation conventions and limits.
+- List validation results, including anything skipped or still unverified.
+- Include screenshots for visible changes using synthetic/public chart data.
+- Keep generated builds, local settings, credentials and personal data out of Git.
+
+Use descriptive commits. Implementation work should include a local commit after
+checks and diff review. A push or publication still needs the repository owner's
+authorization. GitHub workflows run formatting, types, tests, builds, consumer
+validation and a full-history secret scan.
+
+## Documentation and assets
+
+Keep examples runnable with invented positions or documented public reference
+dates/locations. Describe public behavior in the [API reference](docs/api.md)
+and implementation detail in [architecture](docs/architecture.md). Update
+`llms.txt` when navigation changes. Check relative links in the packed docs as
+well as the checkout: website/example assets and development scripts are not packaged.
+
+The [brand notes](https://github.com/yuzuwoeser/astr3/blob/main/site/public/brand/README.txt)
+record wordmark colors, SVG assets, and font attribution. The
+[export font guide](https://github.com/yuzuwoeser/astr3/blob/main/scripts/export-fonts/README.md)
+describes optional outline regeneration and provenance. Keep copyright/license
+notices with redistributed fonts and outlines; do not regenerate them for a
+prose-only change.
+
+Report vulnerabilities using [SECURITY.md](SECURITY.md), not a public issue with
+an exploit or secret. See [the release checklist](docs/releasing.md) for artifact
+and privacy checks before a public release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ASTR3 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/NOTICE

@@ -0,0 +1,38 @@
+ASTR3 source code is MIT licensed. The library build does not bundle dependency code.
+
+The library includes ASTR3 export outline data derived from Noto Sans Regular,
+Noto Sans Symbols Regular and Noto Sans Symbols 2 Regular under the SIL Open Font
+License 1.1. The font copyright notices and full license are in
+export-fonts-OFL.txt alongside the installed JavaScript (dist/ in the tarball),
+and scripts/export-fonts/OFL.txt in source. Source revisions and SHA-256 hashes
+are recorded in scripts/export-fonts/sources.json. The derived outline data
+remains OFL-licensed. Generated chart documents do not inherit that license.
+The website's THIRD_PARTY_LICENSES.txt also contains these notices.
+
+The website bundles the unmodified Righteous Regular (400) font by Brian J.
+Bonislawsky DBA Astigmatic (AOETI), under the SIL Open Font License 1.1.
+Its copyright notice and full license accompany the font in site/public/fonts/OFL.txt
+and are included in the website's THIRD_PARTY_LICENSES.txt. The font is a website asset,
+not part of the library build, and remains under its original license.
+
+Three.js — https://github.com/mrdoob/three.js
+MIT License. Used as an external peer dependency.
+
+Astronomy Engine — https://github.com/cosinekitty/astronomy
+MIT License. Used only by the optional ephemeris entry.
+
+Each dependency's full license remains in its installed distribution. Retain its
+license notices when distributing applications that bundle these dependencies.
+
+Independent fixtures record numerical results from a separately installed Swiss
+Ephemeris 2.10.03. No implementation source or runtime is included or required by
+the library or tests.
+
+The optional website previews also bundle React, Vue, Svelte, Angular, and
+Hotwire dependencies, with their licenses included in the generated website
+THIRD_PARTY_LICENSES.txt. Turbo 8.0.23 omits a standalone license in its npm
+archive; the website retains its upstream MIT-LICENSE from
+https://github.com/hotwired/turbo/blob/v8.0.23/MIT-LICENSE.
+
+The website's syntax highlighting bundles Highlight.js under BSD-3-Clause.
+Its full license is included in the generated THIRD_PARTY_LICENSES.txt.

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# ASTR3
 
-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.
+[Project website and playground](https://yuzuwoeser.github.io/astr3/) · [Deployment and preview](docs/github-pages.md)
+
+<img src="https://raw.githubusercontent.com/yuzuwoeser/astr3/main/site/public/brand/astr3-logo-preview.svg" alt="ASTR3" width="320" />
+
+Explorable astrology wheels for the browser. A framework-neutral TypeScript library built with Three.js, released under MIT.
+
+Select a planet, point, house, aspect, or supplied configuration. Highlight its relationships and connect the selection to your own explanations, tables, tooltips, or panels. Rendering works with precomputed data; the optional browser adapter calculates a natal chart without a backend.
+
+## Use the library
+
+Choose an installation route in the [installation guide](docs/installation.md):
+npm package, a browser ZIP without build tools, or an installable WordPress
+plugin. Use Node.js 24 LTS (minimum 22.12.0) for bundled applications:
+
+```sh
+npm install @yuzuwoeser/astr3 three
+```
+
+The npm package is `@yuzuwoeser/astr3`. Browser downloads keep the `astr3.js`
+filename. For unpublished local changes, run `npm ci && npm pack` in a checkout
+and install the generated `yuzuwoeser-astr3-0.1.1.tgz` tarball. Framework starter
+ZIPs include a local tarball and their own application files.
+
+Mount after the host element exists. For example, add this HTML to a page served
+by your application's bundler:
+
+```html
+<div id="wheel" style="width: min(100%, 640px)"></div>
+<pre id="details"></pre>
+```
+
+```ts
+import { createChart } from '@yuzuwoeser/astr3';
+
+const host = document.querySelector<HTMLElement>('#wheel');
+const panel = document.querySelector<HTMLElement>('#details');
+if (!host || !panel) throw new Error('Mount #wheel and #details first.');
+
+const chart = createChart(host, {
+  data: {
+    bodies: [
+      { id: 'sun', name: 'Sun', longitude: 0 },
+      { id: 'moon', name: 'Moon', longitude: 120 },
+      { id: 'jupiter', name: 'Jupiter', longitude: 240 },
+    ],
+    // Omit aspects to calculate enabled types with configurable orbs.
+    // Supply [] to deliberately display none.
+  },
+});
+
+const unsubscribe = chart.on('selection', ({ details }) => {
+  panel.textContent = details ? JSON.stringify(details, null, 2) : 'Select an object';
+});
+
+chart.select({ kind: 'body', id: 'sun' });
+// Call from your application's unmount handler.
+function unmount() {
+  unsubscribe();
+  chart.dispose();
+}
+```
+
+The wheel resizes as a square; the accessible object list stays below it in document
+flow. Importing `@yuzuwoeser/astr3` is SSR-safe; interactive graphics need a browser and WebGL 2.
+If WebGL is unavailable, the HTML object list remains usable and `chart.error`
+explains the failure. For data-only use in Node or workers, import `@yuzuwoeser/astr3/model`.
+
+## Optional browser calculation
+
+```sh
+npm install astronomy-engine
+```
+
+```ts
+import { createAstronomyProvider } from '@yuzuwoeser/astr3/ephemeris';
+
+const provider = createAstronomyProvider();
+const data = await provider.calculate({
+  utc: '2000-01-01T12:00:00Z',
+  latitude: 51.5074,
+  longitude: -0.1278, // east positive
+  houseSystem: 'placidus',
+});
+
+// Reuse the mounted chart from the previous example.
+chart.update(data);
+```
+
+`@yuzuwoeser/astr3/model` is a headless entry with no DOM, Three.js, or ephemeris imports. `@yuzuwoeser/astr3/ephemeris` imports Astronomy Engine but not Three.js. Renderers and selections never request new calculation data automatically. Any provider implementing `EphemerisProvider` can replace the example adapter.
+
+## Capabilities
+
+- Natal and transit wheels with arbitrary supplied planets/points, unequal house
+  cusps, independent AC/MC axes, and unknown-house support.
+- Eleven aspect types with independent enablement and orbs; supplied aspects and
+  configuration groups remain under the caller's control.
+- Exact longitude markers, bounded label placement, overlap choosers, touch/keyboard
+  selection, and an accessible HTML object list.
+- Two layouts, themes, chart weights, custom glyphs, layers, and per-body visibility.
+- Reusable [JSON appearance templates](docs/api.md#json-templates) with synchronous
+  validation, copied options, and a packaged JSON Schema for natal/transit charts.
+- Browser [SVG/PNG export](docs/api.md#svg-and-png-export) and opt-in
+  [transit animation](docs/transits.md#animated-time-steps) with reduced-motion support.
+
+The initial API is versioned 0.x and may change before 1.0. Automatic patterns, synastry, standalone transit houses, multi-selection, continuous time playback, 3D presentation, and framework wrappers are deferred.
+
+## Natal + transit bi-wheels
+
+Use `createTransitChart` with `{ data: { natal, transit } }`. Both sides accept
+`ChartInput`; IDs remain local to their chart. Selections include `chart: 'natal'`
+or `'transit'`, and cross-aspect selections use `'cross'`. Houses and axes come
+from the natal chart. See the [working example and transit API](docs/transits.md).
+
+## Website, playground, and integrations
+
+From a checkout, run `npm ci` and `npm run dev`, then open the Vite URL and choose **Playground**. The initial
+wheel uses synthetic teaching data with a supplied grand trine. Choose a preset or
+enter UTC time and coordinates to calculate locally with Astronomy Engine.
+
+Choose **Natal + transits** for time stepping and optional animation. **Aspects**
+sets enablement and orbs; **Celestial bodies** controls individual visibility.
+Layout, theme, and chart weight affect presentation. Birth information is never
+sent to a calculation service. See [demo time controls](docs/transits.md#demo-controls)
+for transit-specific behavior.
+
+The website includes runnable JavaScript/TypeScript, React, Vue.js, Svelte, and
+Angular examples, plus HTML, PHP, WordPress, and Ruby on Rails integration guides.
+[Integration overview](docs/integrations.md) explains the browser download and
+canonical examples. `site/` owns the website; `examples/` owns the source shown
+in its guides. `npm run dev` builds previews before starting Vite; restart it
+after changing an example.
+
+Choose [JSON templates](https://yuzuwoeser.github.io/astr3/examples/json-templates/)
+for a live preview and downloadable appearance presets. Import a JSON file and
+spread `resolveChartTemplate(template)` into `createChart` options, followed by
+your own `data` and `ariaLabel`. Transit charts use `resolveTransitChartTemplate`.
+See the [template API](docs/api.md#json-templates) for validation and overrides.
+
+## Documentation and validation
+
+- [Installation and release downloads](docs/installation.md)
+- [Framework, CMS, and server-rendered integrations](docs/integrations.md)
+- [Integration coverage roadmap](docs/integration-roadmap.md)
+- [Agent integration: headless data and browser lifecycle](docs/agent-integration.md)
+- [API, exported helpers, events, and data contracts](docs/api.md)
+- [Transit bi-wheel API](docs/transits.md)
+- [Calculation conventions and tested accuracy](docs/calculations.md)
+- [Architecture and integration](docs/architecture.md)
+- [Contributing and local setup](CONTRIBUTING.md)
+- [Instructions for repository coding agents](AGENTS.md)
+- [Documentation index for LLMs](llms.txt)
+- [Release and privacy checklist](docs/releasing.md)
+- [Security reporting](SECURITY.md) and [changelog](CHANGELOG.md)
+
+Run `npm run check` and `npm run format:check` for local validation. Browser tests
+run separately with `npm run test:browser`; setup and coverage limits are in
+[Contributing](CONTRIBUTING.md).
+
+## License and assets
+
+ASTR3 source is MIT licensed. Dependency and bundled font attribution is in
+[NOTICE](NOTICE). The Righteous wordmark font and Noto export outlines retain
+their SIL OFL licenses. Reusable logos and palette specifications are in the
+[brand asset notes](https://github.com/yuzuwoeser/astr3/blob/main/site/public/brand/README.txt).

package/SECURITY.md

@@ -0,0 +1,32 @@
+# Security policy
+
+Only the latest 0.1.x release is maintained for security fixes. There is no
+guaranteed response time. The API is experimental and versions before 1.0 may
+change.
+
+## Report privately
+
+Private vulnerability reporting is not currently enabled for this repository.
+Open an [issue](https://github.com/yuzuwoeser/astr3/issues) asking for a private
+reporting channel **without disclosing the vulnerability, exploit, credentials,
+or personal chart data**. Wait for a private channel before sharing sensitive
+details. If maintainers enable **Security → Report a vulnerability**, use that
+private channel instead. Public issues are suitable for ordinary bugs reproduced
+with synthetic data.
+
+Include the affected version, runtime/browser, impact and a minimal reproduction.
+Use invented chart data. Share secrets only to identify a leak through the agreed
+private channel, and rotate exposed credentials promptly.
+
+## Scope and privacy
+
+The library renders caller-supplied data; the optional Astronomy Engine adapter
+calculates locally. First-party code includes no account service, telemetry or
+chart storage. Host applications control persistence, network access and custom
+HTML. Treat names, metadata and interpretation text as untrusted application data;
+use `textContent` for plain text rather than interpolating it into HTML.
+
+Release checks scan Git history and distributable contents for secrets and review
+fixtures for personal information. Automated secret detection cannot establish
+that arbitrary chart coordinates or screenshots are safe to publish. Review
+those manually and keep private datasets outside the repository.