Papure/spec.md

# Lecture Notes App — Architecture Doc v1

## 1. Page Tree Model ("Comb")

One canvas = one tree = one `.pdf` file.

- **Trunk**: a single vertical chain of pages. Grows **up or down** (both allowed).
- **Branch**: a horizontal chain of pages attached to exactly one trunk page, going **left or right**.
  - A branch can only ever continue in the direction it started (strictly linear — no sub-branches off a branch).
  - A trunk page can have at most one left branch and one right branch.
- **PDF import**: creates a chain of pages in whatever direction you pick when placing it (up/down = extends the trunk, left/right = becomes a branch off the trunk page you clicked). Only one trunk exists per canvas — additional imported PDFs must attach as a branch off some trunk page, or extend an existing branch further outward in its established direction.
- Each free side of the active page shows a small "+" circle just off its edge; tapping it (or `Alt+Arrow`) adds a blank page there. A quick finger fling toward a free side offers a page there for a few seconds: that side's "+" pulses, or, if it is off screen, an "Add page" button appears at that edge of the screen. The fling never adds a page by itself, and can be turned off in Settings.
- The canvas background is a faint grid with one cell per active page, aligned to its edges; Settings can hide it or subdivide it.
- Deleting a page removes it (undo via Ctrl+Z); no permanent trash.
- Default zoom: one page fills the screen. Zoom out reveals the tree.
- Pages default to A4, or auto-match the aspect ratio of an imported PDF page; resizable manually otherwise (page menu: presets, or a custom size in mm).

## 2. Flatten Algorithm (tree → linear page order, e.g. for PDF page order / print)

Starting at the **topmost** trunk node, walk down:

```
for each trunk_node, top → bottom:
    emit trunk_node
    emit left_branch pages, closest-to-trunk → outward
    emit right_branch pages, closest-to-trunk → outward
```

This is recomputed at export/save time (not creation order), since the trunk can grow upward later and shift what "topmost" means.

## 3. File Format

One canvas = **one `.pdf` file**, dual-layer:

- **Visual layer** (any standard PDF viewer sees this): rendered markdown as real vector text, ink drawn as PDF Ink annotations, original imported PDF content where applicable. Fully readable/printable by anyone, no app required.
- **Source-of-truth layer** (embedded file attachments, invisible in normal viewers): raw markdown source per page, full vector stroke data (points + pressure + tilt — richer than what Ink annotations can hold), and grid metadata (each page's tree position, size, and which PDF import it originated from, for provenance search).
- App reads the attachment layer first to reconstruct the live editable canvas; falls back to parsing visual content only if attachments are missing.

**Libraries**: `pdf-lib` (write/edit/attach), `pdf.js` (render/import).

**Trade-off accepted**: binary PDFs mean no line-level git diffs. Flag for later if this becomes annoying — we could add a parallel auto-generated `.md` export per canvas purely for git-diff readability, PDF stays canonical.

## 4. Organization

Canvases (PDF files) live in a **file tree** you define, e.g. `school/english/lecture1.pdf`, `school/math/lecture2.pdf`, `work/...`. Folders are purely organizational, no canvas of their own.

## 5. Sync & Storage

- Repo-backed (GitHub for now; GitLab not implemented), one file per canvas.
- PWA: offline-first, caches locally, explicit save/sync pushes to repo.
- Multi-device: git pull/push is the sync mechanism (not real-time collab).

## 6. Tech Stack (tentative)

- **Frontend**: SvelteKit, deployed on your VPS, installable as PWA.
- **Ink input**: Pointer Events + pressure (your existing artifact — pending).
- **PDF read/write**: pdf.js + pdf-lib.
- **Storage**: IndexedDB locally; Git repo via the GitHub REST API (token in the browser, no proxy).

## 7. Confirmed Product Features

- Live-rendered markdown (background layer) + vector ink (foreground layer), never converted to text.
- Full ink toolset: colors, highlighter, eraser.
- Search across typed markdown text.
- Pages remember their PDF-import origin, searchable.
- No export needed beyond the PDF itself (for now).

## 8. Sync, Auth & Conflicts (resolved)

- **Git auth**: personal access token stored in the browser/PWA (no backend proxy, for now).
- **Save model**: autocommit + periodic push, plus a manual "sync now" button that does pull + push on demand.
- **Conflicts**: newer version wins (timestamp-based), no merge UI for now.
- **Repo size**: not a concern for now — revisit if it becomes a problem.

## 9. Pen Input & Palm Rejection

Source: user-provided `palm-rejection-test.html` test harness. The acceptance policy carries over almost verbatim:

- `pointerType === 'pen'` is always accepted; its down/move/up updates `lastPenActivityTime`.
- A `touch` pointer is rejected if any of: a pen stroke is active or was active within the last ~5s, its contact ellipse (`width`/`height`) exceeds ~35px (palm heel vs. fingertip), it's within 150ms of the last pen activity, or a pen is currently hovering (armed lockout before it even touches down).
- A touch stroke already in progress gets cut off mid-stroke if pen activity appears.

**How the app applies it** (`src/lib/ink/palm.ts`):
- Each touch is evaluated with an intent. `draw` (finger ink) gets the full policy above. `navigate` (pan, pinch, and taps on canvas buttons such as the add-page "+") skips the 5 s pen session and the hover lockout, so fingers can move around and tap between pen strokes; pen-down, wide contacts and the 150 ms window still reject it.
- Once a pen has been used, fingers only navigate. "Draw with finger" in Settings turns finger ink off entirely.
- Each rule (pen session, wide contact, timing, hover) can be switched off in Settings → Pen & touch.
- An interrupted pointer (`pointercancel`) drops the stroke or erase in progress instead of committing it.

**Ink engine (implemented)**:
- `StrokeRecorder.recordPoint()` stores `x, y, pressure, tiltX, tiltY, t` per sample in a flat `Stroke.points` array (stride 6); rendering replays it. Tilt is recorded but not yet used for rendering.
- Outlines are smoothed with `perfect-freehand`; mouse and finger strokes simulate pressure.
- Pen, highlighter (translucent, no thinning) and stroke eraser, with configurable colour palettes; the pen's eraser end erases too.
- Undo/redo covers ink, erasing and page-tree changes.
- Strokes are written to the PDF both as Ink annotations and as JSON attachments.

## 10. Open Items

- [ ] Conflict copies: sync currently lets the newer version win silently; keep the losing version as a separate file.
- [ ] Tell the user when a new version of the app has been deployed (the service worker updates, but the open tab keeps old code until reload).
- [ ] CI that runs `check`, `test` and `build` on every pull request.
- [ ] Use recorded tilt for rendering.
- [ ] GitLab sync.