# Source organization

The root package is a small public facade in [`api.mbt`](../api.mbt).
Applications import `Lampese/mathplotlib`; the plotting methods and default
`@mathplotlib` alias remain unchanged. The 0.2.1 distribution combines static
plotting and the browser component in one module; see [installation and path migration](PUBLISHING.md).

This follows the [pdf-viewer package organization](https://github.com/moonbit-community/pdf-viewer/blob/master/docs/architecture.md):
a small root facade, consumer tests in `tests/api`, generated resources with
clear owners, and implementation files split by responsibility within packages.
MoonPlot retains its existing focused packages rather than placing the entire
plotting library in one engine package.

## Package map

| Location | Responsibility |
| --- | --- |
| [`api.mbt`](../api.mbt) | Public type/function re-exports and `plot_svg` convenience function |
| [`core/`](../core) | Points, bounds, typed errors, styles, masked data, and color values |
| [`scene/`](../scene) | Figures, Axes, artists, layout state, and checked drawing preparation |
| [`drawing/`](../drawing) | Immutable SVG snapshots and platform-independent point hit testing |
| [`backend/svg/`](../backend/svg) | SVG layout, geometry, and serialization |
| [`ticker/`](../ticker) | Numeric/date locators, formatters, categories, and scales |
| [`transforms/`](../transforms) | Affine transforms, bounds, paths, and geometry |
| [`pyplot/`](../pyplot) | Stateful convenience facade over Scene |
| [`internal/`](../internal) | Shared render IR, host bridges, PNG helpers, generated color resources |
| [`rabbita/`](../rabbita/README.md) | JS-only interactive DOM package in the same module |
| [`cmd/`](../cmd) | Runnable static plotting examples |
| [`tests/api/`](../tests/api) | Consumer tests importing only the public root facade |
| [`tests/integration/`](../tests/integration) | Independent packages isolating process-global epoch/configuration tests |
| [`scripts/`](../scripts) | Fixed-upstream reference collection and resource generators |
| [`tools/`](../tools) | Repository maintenance checks |
| [`testdata/`](../testdata) | Independent oracle data, provenance, regeneration notes, and packed test fixtures |
| [`assets/`](../assets) | Checked-in sample output and actual UI screenshots |

`rabbita/moon.pkg` and its browser executables declare `supported_targets = "js"`.
The core facade, Scene, Drawing and static renderer do not import UI packages.
Dependency declarations belong to the module, so installing it also resolves
Rabbita and its transitive dependencies; package-level compilation preserves
the static backend boundary. There is no nested adapter module or adapter
`moon.work` in the current layout.

Blackbox and whitebox tests for an implementation package stay beside it when
they exercise that package's contracts or private helpers. Moving whitebox
tests into unrelated packages would require exposing private implementation.
The root's consumer tests do not need that access and have their own package.

## Files inside the main packages

`backend/svg/render.mbt` now contains the top-level rendering entry points.
`panel_layout.mbt` computes panel rectangles, and `panel.mbt` dispatches their
artists. `coordinates.mbt`, `line.mbt`, `markers.mbt`, `bar.mbt`, `polygon.mbt`,
`reference.mbt`, `grid.mbt`, `secondary_axis.mbt`, and `spines.mbt` own their
respective geometry. Annotation, table, legend, colorbar, pie, statistics, and
quiver serialization each have a named file. Existing image and tick-layout
files retain their responsibilities.

`pyplot/state.mbt` holds the current Figure/Axes lifecycle. Plotting methods,
statistics, vector plots, pcolor, streamplot, contour, triangulation, images,
tables, annotations, axis controls, and output live in their corresponding
files. `scene/figure.mbt` holds the Figure API; `artist_model.mbt`,
`axes_state.mbt`, `axes.mbt`, and `color_cycle.mbt` separate shared model values,
Axes lifecycle/settings, and color-cycle state.

These splits move complete `///|` blocks within the same compilation unit.
They do not add public helper functions or introduce another layout algorithm.

## Generated data and reference tests

`internal/color_names` owns the complete pinned named-color table. Its three
generated files separate standard colors, XKCD colors, and grey/gray aliases.
Each entry retains exact IEEE-754 channel bits; a small private loader creates
the lookup map. Scene keeps the existing color parsing and lazy validation
behavior and delegates only exact named lookup.

The largest Logit sort references use small data-driven test harnesses and
losslessly packed fixtures under `testdata/packed`. They retain every original
case, scalar origin, input bit, expected output bit, and complete permutation.
Fixtures are derived from the checked-in independent oracle JSON, not from the
sorting implementation. Moon's embed step emits ignored, test-only loaders.
Production executables do not link these resources; source distribution keeps
the packed inputs required by the package's pre-build hooks.
See the [packed fixture guide](../testdata/packed/README.md) for the format and
saved-oracle verification commands.

Other generated numerical references still have large case files. Their
`*_reference_test.mbt` / `*_reference_wbtest.mbt` names and provenance separate
them from maintained implementation. They are not removed or mechanically
sharded to lower a line count. New large reference suites should use the packed
fixture pattern rather than duplicate large arrays as source code.

## Maintenance checks

```sh
python3 tools/check_structure.py
moon check --target all
moon test tests/api tests/integration/* --target all
moon info
moon fmt
```

The structure check limits maintained files to 2,000 lines and keeps root files
restricted to the facade, manifests, generated interface, and project metadata.
It reports generated references separately using their headers and naming
convention. `--json` prints the complete source inventory for deeper review.
Review generated `.mbti` changes after a move: file splits should preserve
public interfaces; moved isolated test package names and new internal packages
are expected exceptions.

Build output, dependency caches, generated fixture loaders, and agent working
state are ignored by Git. They are not source files to edit or move into a
product package. Reference reproduction still uses `scripts/` and `testdata/`
so existing pinned source checks and relative imports remain intact.

## Organization verification, 2026-10-24

| Item | Before | After |
| --- | --- | --- |
| Tracked root files | 23 | 10 |
| SVG main rendering file | 4,158 lines | 136 lines, with named geometry/layout files |
| pyplot state file | 2,353 lines | 157 lines, with named feature files |
| Scene figure file | 1,588 lines | 534 lines, with separate model/Axes files |
| Generated Scene color match | 6,559 lines | 6-line bridge to complete internal resource tables |
| Two largest generated sort tests | 23,473,639 bytes | 4,172 bytes of harnesses plus a small shared decoder |
| Complete packed sort resources | Duplicated as test source | 1,993,905 bytes of derived data; original JSON retained |

All 332 moved production blocks are byte-preserved apart from blank separators.
The 22,172 explicitly named source tests retain the same names and multiplicity;
that count is separate from runtime test totals, which also include other test
forms and target-specific cases. No existing public interface changed.

The final complete suite passed **22,264/22,264** on wasm, wasm-gc, and native,
and **22,271/22,271** on JS. `moon info`, `moon fmt`, and four-target check passed
with seven existing Ref deprecation warnings and no new errors. The public
consumer and isolated configuration test sets each passed 18/18 per target.
All three native plotting examples ran successfully; the preview and gallery
SVGs are byte-identical to their saved assets. The optional adapter passed 7/7
tests and 11 real-browser interaction/layout checks with no page errors. Its
UI screenshot is also byte-identical. The production JS bundle was checked to
exclude test fixture names, format magic, and encoded payload prefixes.
Detailed local evidence is in `.moonagent/checkpoints/repository-organization/`;
these ignored logs are not required to reproduce the public commands above.