# Graph Family Public Specification

This document describes the public specification of the graph family centered on `graph.html`.

Scope:

- `graph.html`
- `party-proportional.html`
- `party-constituency.html`

Primary goals:

- let humans confirm the role and boundary of the graph family
- give AI systems a stable public reading path
- state what the graph surface reads, renders, and does not promise
- summarize what the current public graph can actually do

## 1. Public routes

- canonical public route: `/graph.html`
- route family:
  - `/graph.html`
  - `/party-proportional.html`
  - `/party-constituency.html`
- canonical public base: `https://jp-election-public-ja.pages.dev`

This specification is published as an independent document linked from the lower part of the graph page.

## 2. Role of the graph family

`graph.html` is a presentation surface for municipality, prefecture, and national series exploration.

The page:

- reads published packets
- uses a selector index to choose municipalities
- does not recompute aggregate series on its own in the browser
- handles locale, theme, and layout as presentation-layer concerns

The page does not:

- read `ops/status/` as its authority source
- expose internal worklogs or private-viewer-only material
- invent series that are not present in the public packet

## 3. Main inputs

### 3.1 graph packet

Primary packet:

- `/analysis/graph-family/latest/graph-page.json`

This packet carries the shell contract for the graph family.

Main roles:

- page metadata
- source release version
- scope coverage
- page asset paths
- dataset entry public keys
- pipeline stage status

### 3.2 selector index

Municipality selector:

- resolved through `selector_index_path`

Main fields:

- `jis_code`
- `prefecture_code`
- `prefecture_name`
- `municipality_name_ja`
- `graph_payload_path`
- `stats_series_path`
- `party_votes_path`

The graph page uses the selector index to determine both available municipality choices and the payload path to read.

### 3.3 graph payload

Municipality-scoped payloads are read from `graph_payload_path`.

Main contents:

- `summary`
- `timeline_slots`
- `components`
- `stats_series`
- `stats_component_series`
- `parties`
- `party_vote_series`
- `party_series`

The public page uses this payload for rendering. Canonical fact judgment stays outside the page and depends on public packets and dictionaries.

## 4. Coverage

Primary scopes of `graph.html`:

- municipality
- prefecture
- national

The current page is organized as a municipality-first explorer.

It also carries auxiliary:

- prefecture series
- national series

inside the same family.

## 5. What This Graph Can Do

The current `graph.html` should be treated as a public explorer with these capabilities.

- explore municipality, prefecture, and national series
- switch between `ja / en`
- switch between `mobile / desktop / auto`
- switch between party-vote series and turnout/stat series
- filter by vote system (`proportional / constituency / block / multi`, etc.)
- limit the visible time range with start / end selectors
- add a bar overlay when needed
- inspect per-series tooltips with date, election type, vote system, and scope
- show party-leader labels for some parties when public leader data exists
- create up to three custom comparison series (`custom_a`, `custom_b`, `custom_c`)
- read an on-page legend for the currently rendered series

AI systems should treat this page as an interactive explorer over public packets, not as a static narrative page.

## 6. UI contract

### 6.1 layout

Layout modes:

- `auto`
- `mobile`
- `desktop`

Default is `auto`, which resolves to mobile or desktop from viewport width.

### 6.2 locale

Locales:

- `ja`
- `en`

In English mode, party labels prefer `name_en` when available. When no English name exists, the page falls back to a public presentation label.

### 6.3 party blocks

The party selector is split into two blocks:

- `As of 2026-02-08`
- `Merged / dissolved`

Meaning:

- the upper block is the main group for series present in the `2026-02-08` election set
- the lower block contains older series that are not in the main group

Inside the upper block, the page also separates:

- `Proportional`
- `Constituency`

Within each family:

- series that contest in the `2026-02-08` election set appear first
- continuing series that do not contest there are placed after them

On mobile:

- `As of 2026-02-08` is open by default
- `Merged / dissolved` is collapsed by default

### 6.4 custom series

The page exposes three synthetic comparison series:

- `custom_a`
- `custom_b`
- `custom_c`

Meaning:

- user-defined aggregates of existing displayed series
- combined in the browser for presentation
- not canonical release-fact categories

Current UI contract:

- each custom series has its own visibility toggle
- each custom series has its own member selection
- the custom editor follows the same current / legacy ordering used by the main selector

### 6.5 year selector

Election years use the existing range selector.

It is treated as:

- start
- end

range selection.

### 6.6 axis / legend / tooltip

Current rendering contract:

- the X axis follows actual `election_date`
- visible labels use `YYYY/M/D + short election type`
- the Y axis is recalculated from the visible series
- the top bound uses the nearest upper tick above the maximum visible value
- the legend sits below the graph
- custom series appear as independent legend rows

Tooltip contract:

- election date
- election type
- vote system
- selected scope
- value
- party leader label when available

## 7. Display priorities

This page is a series explorer, so it prioritizes showing the graph itself first.

Especially on mobile, the preferred order is:

- graph first
- selector second
- auxiliary controls later

## 8. AI reading guide

When AI systems read this surface, they should proceed in this order.

1. Read `graph-page.json` to confirm the page contract and scope status
2. Read the selector index to obtain available municipality choices and payload paths
3. Read the graph payload for `timeline_slots / party_series / stats_series / party_vote_series`
4. Read public party continuity dictionaries when lineage interpretation matters
5. Treat locale labels as presentation fields and prefer `party_id / jis_code / election_set_key / seriesId` for joins

Additional public dictionaries relevant to AI interpretation:

- `party_master`
- `party_lineage_link`
- `party_graph_stream`
- `party_graph_stream_member`
- `party_leader_term`

Current UI semantics that AI should understand:

- `Merged / dissolved` means “older series not in the 2026-02-08 main block,” not necessarily a legal dissolution label
- custom series are user-defined aggregates, not canonical lineage classes
- on-screen colors are visual aids, not authority keys

Notes:

- UI chips and button labels are not authority sources
- do not infer canonical ordering from on-screen order alone
- a missing series may reflect packet coverage rather than a rendering error

## 9. Public boundary

This specification and the graph family are part of the public surface.

Allowed:

- graph packets
- selector indices
- public docs
- public analysis payloads

Not allowed:

- internal ops memos
- private-viewer-only routes
- internal paths that leak provenance
- ad hoc notes that overwrite release truth

Canonical release truth remains in the public release manifest and public catalog.

## 10. Related public documents

- `/docs/README.md`
- `/docs/english-conversion-guide.md`
- `/docs/tidy-rule.md`
- `/docs/artifact-layers.md`
- `/docs/normalization-rules.md`

## 11. AI Short Summary

For a fast AI-oriented understanding:

- `graph.html` is a municipality-first public explorer
- authority comes from public packets and public dictionaries, not from the UI itself
- current / legacy / custom are UI groupings, not release-truth layers
- `party_id`, `seriesId`, `election_set_key`, and `jis_code` are the main join keys
- tooltips and legends help users read the page but do not replace canonical fact tables

## 12. Stability

This document describes the public contract of the graph family.

Likely to change:

- visual layout
- link placement
- selector grouping

Expected to remain relatively stable:

- packet-first reading
- first-class selector index
- no browser-side aggregate regeneration
- no mixing of public and internal boundaries