# Spine — data model and index page

Extends [`spine-spec.md`](../../spine-spec.md) with a concrete Org data structure
and defines the first real view: an index page that reads from `spine.org` and
displays books grouped by lifecycle status.

## Data model (`spine.org`)

Each book is a top-level headline. The TODO keyword is the lifecycle state.
Properties hold structured metadata. The headline body holds reading notes
as a plain Org list with inactive timestamps.

### TODO states

```org
#+TODO: WANT(w) READING(r) | READ(d) ABANDONED(a)
```

### Properties

| Property | Required | Value |
|---|---|---|
| `:AUTHOR:` | yes | freeform string |
| `:ISBN:` | no | freeform string |
| `:COVER:` | no | path relative to `spine.org` |
| `:FORMAT:` | no | `hardcover` \| `ebook` \| `audiobook` |
| `:REC_BY:` | no | who recommended it |
| `:REC_NOTE:` | no | why it's on your radar |
| `:RATING:` | no | 1–5, set when moved to `READ` |
| `:ADDED:` | no | `[YYYY-MM-DD]` date added to spine |
| `:ID:` | yes | stable unique identifier (e.g. `8c1e-uow`) |

Missing or empty properties → `nil` at read time. The view decides how to
render nils.

### Tags

Org tags on the headline = categories (e.g. `:scifi:literary:`).
Tags filter and inherit natively in Org.

### Body: reading notes

A plain Org list in the headline body. Each item is prefixed with an inactive
timestamp `[YYYY-MM-DD]`. Appending a note = inserting one list item.

```org
- [2026-03-02] The two-track structure is doing something I can't name yet.
```

### LOGBOOK

State-change history is captured automatically by `org-log-into-drawer`.
This gives us the "when read" timeline for free — each state transition gets
a timestamped entry.

```org
:LOGBOOK:
- State "READING" from "WANT" [2026-02-20]
:END:
```

### Full example entry

```org
* READING Use of Weapons
:PROPERTIES:
:AUTHOR:  Iain M. Banks
:ISBN:    978-0316029193
:COVER:   covers/use-of-weapons.jpg
:FORMAT:  audiobook
:REC_BY:  Priya
:REC_NOTE: If you liked Player of Games, this one will wreck you
:RATING:  
:ADDED:   [2026-02-20]
:ID:      8c1e-uow
:END:
:LOGBOOK:
- State "READING" from "WANT" [2026-02-20]
:END:
- [2026-03-02] The two-track structure is doing something I can't name yet.
- [2026-03-07] Zakalwe's competence reads as a wound.
```

## Architecture

Model/view split. Data extraction from Org is isolated from HTML rendering.

```
spine.org ──→ [spine-books] ──→ book plists ──→ [spine-render-index] ──→ HTML
```

### Model layer: `spine-books`

Opens the Org file, walks top-level headlines with `org-element`, returns a
list of plists — one per book.

```elisp
(spine-books) → list of plists
```

Per-book plist shape:

```elisp
(:id       "8c1e-uow"
 :title    "Use of Weapons"
 :status   "READING"
 :author   "Iain M. Banks"
 :isbn     "978-0316029193"
 :cover    "covers/use-of-weapons.jpg"
 :format   "audiobook"
 :rec_by   "Priya"
 :rec_note "If you liked Player of Games…"
 :rating   nil
 :added    "[2026-02-20]"
 :tags     ("scifi" "literary")
 :notes    (("[2026-03-02]" "The two-track structure…")
            ("[2026-03-07]" "Zakalwe's competence…")))
```

**Org file not found or invalid:** `spine-books` returns `nil` and messages a
warning. The `condition-case` around the parse catches malformed Org.

**Reading strategy:** visit `spine.org` in a temp buffer, parse with
`org-element-parse-buffer`, walk top-level headlines. Full scan — adequate
for ~tens of books. No `org-ql` yet; add it later when live filtering is needed.

### View layer: `spine-render-index`

Takes the book list and an optional selected ID, returns an HTML string.
No CSS, no JavaScript — structural HTML with CSS class names matching
mockup A so styles drop in later.

**Grouping:** books partitioned by status in this order:
`WANT` → `READING` → `READ` → `ABANDONED`.
Each group gets a header with count.

**Collapsed row per book:**
- Format glyph: `[H]` hardcover, `[E]` ebook, `[A]` audiobook (nothing if unset)
- Title + author
- Tags
- Recommendation trail (`REC_BY: REC_NOTE`) when present
- Status pill

**Expanded detail** (triggered by `?id=` query param):
- Reading log: each note as date + text
- Properties: format, ISBN, rating, added date

**Section structure:**
```html
<div class="frame">
  <div class="titlebar">Spine</div>
  <div class="group">WANT (3)</div>
  <div class="row">…</div>
  <div class="row">…</div>
  <div class="row">…</div>
  <div class="group">READING (1)</div>
  <div class="row selected">
    <div class="detail">
      <!-- expanded notes for selected book -->
    </div>
  </div>
</div>
```

**Empty state:** when `spine-books` returns `nil` → page with "No books yet."
message.

### Handler

```elisp
(defservlet index text/html ()
  (let ((books (spine-books)))
    (if books
        (insert (spine-render-index books
                  (ht-get (ht-from-query-string (httpd-query-string)) "id")))
      (insert (spine-render-empty-state)))))
```

- `/` → index, all books collapsed
- `/?id=8c1e-uow` → index with that book's detail expanded
- Bogus `?id=` → no expansion, normal collapsed view

### Configuration

```elisp
(defvar spine-org-file "~/spine/books.org"
  "Path to the spine.org data file.")
```

Overridable before load.

## Error handling

| Case | Behavior |
|---|---|
| `spine.org` missing | `spine-books` returns `nil` → empty-state page |
| `spine.org` invalid Org | `condition-case` around parse, message error, return `nil` |
| Bogus `?id=` param | no expansion, normal collapsed view |
| Package/bootstrap failures | surfaced at startup (existing scaffold behavior) |

## Out of scope

- Write endpoints (add book, add note, set status/rating/format)
- CSS styling
- JavaScript interactivity
- Cover image display
- `org-ql` integration
- Search or filtering beyond status grouping

## Acceptance

- [ ] `spine-books` parses a sample `spine.org` and returns correct plists
- [ ] Missing properties → `nil`, not errors
- [ ] `/?id=...` expands the matching book's detail
- [ ] Empty `spine.org` (no headlines) → empty list, not error
- [ ] Missing `spine.org` → empty-state page, no crash
- [ ] Groups appear in order: WANT, READING, READ, ABANDONED
- [ ] Groups with zero books are omitted from output