eng-pad/DESIGN.md

# DESIGN.md — eng-pad Technical Design

## Overview

eng-pad is an Android note-taking app for EMR pen devices. It provides a
notebook-based writing surface with a guide grid, four fixed pen sizes, line
and box drawing tools, and PDF/JPG export. Target devices are the Supernote
Manta (Android 11) and the Daylight DC-1 (Android 13).

## Architecture

**Kotlin + Jetpack Compose + Custom Canvas View.**

The app uses a single-Activity architecture with Jetpack Compose for UI
chrome (notebook list, page list, toolbar, dialogs) and Compose Navigation
for screen transitions. The drawing surface is a custom `View` subclass
(`PadCanvasView`) hosted inside Compose via `AndroidView` — Compose's
`Canvas` composable does not provide direct access to `MotionEvent` dispatch
or hardware-accelerated `Path` rendering, both of which are critical for
low-latency stylus input.

### Screen Flow

```
NotebookListScreen -> PageListScreen -> EditorScreen
       |                   |                |
  Create/delete       Page grid,       PadCanvasView +
  rename, filter,     add/delete/      Toolbar (Compose)
  sort notebooks      reorder pages
```

Three Compose navigation destinations:

| Route                  | Screen             | Purpose                        |
|------------------------|--------------------|--------------------------------|
| `notebooks`            | NotebookListScreen | List, create, delete, rename notebooks; filter and sort |
| `pages/{notebookId}`   | PageListScreen     | Page thumbnails, add/delete pages, drag-to-reorder |
| `editor/{notebookId}?pageId={pageId}` | EditorScreen | Drawing canvas + toolbar |

### Dependency Stack

| Layer        | Technology                  | Purpose                         |
|--------------|-----------------------------|---------------------------------|
| UI           | Jetpack Compose + Material3 | Screens, toolbar, dialogs       |
| Drawing      | Custom View + Canvas API    | Stroke rendering, input         |
| State        | ViewModel + StateFlow       | Reactive UI state               |
| Persistence  | Room (SQLite)               | Notebooks, pages, strokes       |
| Preferences  | SharedPreferences           | Last notebook, UI state restore |
| Async        | Kotlin Coroutines           | Background DB operations        |
| Navigation   | Compose Navigation          | Screen routing                  |
| Export       | Android PdfDocument API     | PDF generation                  |
| Export       | Bitmap + JPEG compress      | JPG generation                  |
| Share        | FileProvider + Intents      | PDF/JPG sharing (Dropbox, etc.) |

No external drawing libraries. The Android `Canvas` + `Path` + `Paint` API
is sufficient and avoids dependencies that may behave unpredictably on e-ink
displays.

## Coordinate System

All stroke data is stored in **canonical coordinates at 300 points per inch**
for high precision with fine pen strokes. Coordinates are scaled to 72 DPI
during PDF export (multiply by 72/300 = 0.24).

| Page Size | Inches   | Canonical Points  |
|-----------|----------|-------------------|
| Regular   | 8.5 x 11 | 2550 x 3300      |
| Large     | 11 x 17  | 3300 x 5100      |

### Grid

The guide grid uses ~5 squares per inch = 300/5 = **60 points** per grid
square. The grid is drawn as thin gray lines on screen but excluded from PDF
export, JPG export, and any other output.

### Pen Sizes

Four fixed stroke widths:

| Pen   | Millimeters | Canonical Points |
|-------|-------------|------------------|
| 0.38  | 0.38 mm     | 4.49 pt          |
| 0.50  | 0.50 mm     | 5.91 pt          |
| 0.60  | 0.60 mm     | 7.09 pt          |
| 0.70  | 0.70 mm     | 8.27 pt          |

No pressure sensitivity — stroke width is uniform for a given pen size.
The PEN tool remembers the last selected size. Long-press the pen button
to open the size picker.

### Screen Transform

A `Matrix` maps canonical coordinates to screen pixels. The matrix encodes
the current zoom level and pan offset. All stylus input coordinates are
transformed through the inverse matrix before being stored, ensuring strokes
are always in canonical space regardless of zoom.

```
canonical -> [viewMatrix] -> screen pixels
screen pixels -> [inverseMatrix] -> canonical
```

Zoom range: dynamic minimum (page fills viewport) to 4x. Pan is clamped so
the page cannot scroll entirely off-screen.

## Tools

| Tool   | Behavior | Sub-options |
|--------|----------|-------------|
| PEN    | Freehand drawing with active pen size | 4 sizes via long-press menu |
| LINE   | Straight line from pen-down to pen-up | Plain, arrow, double-arrow, dashed via long-press menu |
| BOX    | Rectangle from corner to corner | Uses current pen size |
| ERASER | Touch a stroke to delete it (stroke-level) | — |
| SELECT | Rectangle selection, then cut/copy/delete/paste | — |
| MOVE   | Tap and drag individual strokes | — |

## Data Model

### SQLite Schema (Room)

```sql
CREATE TABLE notebooks (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    title       TEXT NOT NULL,
    page_size   TEXT NOT NULL CHECK(page_size IN ('regular', 'large')),
    created_at  INTEGER NOT NULL,  -- epoch millis
    updated_at  INTEGER NOT NULL,  -- epoch millis
    last_page_id INTEGER NOT NULL DEFAULT 0  -- resume position
);

CREATE TABLE pages (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    notebook_id INTEGER NOT NULL REFERENCES notebooks(id) ON DELETE CASCADE,
    page_number INTEGER NOT NULL,
    created_at  INTEGER NOT NULL,
    UNIQUE(notebook_id, page_number)
);

CREATE TABLE strokes (
    id           INTEGER PRIMARY KEY AUTOINCREMENT,
    page_id      INTEGER NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
    pen_size     REAL NOT NULL,       -- width in canonical points
    color        INTEGER NOT NULL,    -- ARGB packed int
    point_data   BLOB NOT NULL,       -- packed floats: [x0,y0,x1,y1,...]
    stroke_order INTEGER NOT NULL,    -- z-order within the page
    created_at   INTEGER NOT NULL,
    style        TEXT NOT NULL DEFAULT 'plain'  -- plain, dashed, arrow, double_arrow
);

CREATE INDEX idx_strokes_page ON strokes(page_id);
CREATE INDEX idx_pages_notebook ON pages(notebook_id);
```

Database version: 3. Migrations add `style` column to strokes and
`last_page_id` column to notebooks.

### Stroke Point Encoding

Points are stored as a `BLOB` of packed little-endian floats:
`[x0, y0, x1, y1, x2, y2, ...]`. A stroke with N points uses N x 2 x 4
bytes. A typical stroke of 200 points = 1600 bytes. This is ~10x more
compact than JSON and eliminates parsing overhead.

```kotlin
// Encode
fun FloatArray.toBlob(): ByteArray {
    val buf = ByteBuffer.allocate(size * 4).order(ByteOrder.LITTLE_ENDIAN)
    for (f in this) buf.putFloat(f)
    return buf.array()
}

// Decode
fun ByteArray.toFloatArray(): FloatArray {
    val buf = ByteBuffer.wrap(this).order(ByteOrder.LITTLE_ENDIAN)
    return FloatArray(size / 4) { buf.getFloat() }
}
```

### Stroke Styles

The `style` column stores a string constant identifying the stroke's visual
style. This applies to LINE tool strokes and is stored in the DB so rendering
is consistent across sessions.

| Style          | Rendering |
|----------------|-----------|
| `plain`        | Solid line (default for freehand, box, and plain lines) |
| `dashed`       | Dashed line pattern |
| `arrow`        | Solid line with arrowhead at endpoint |
| `double_arrow` | Solid line with arrowheads at both ends |

## Input Handling

### Tool Type Dispatch

The EMR digitizer reports stylus events as `TOOL_TYPE_STYLUS` and finger
touches as `TOOL_TYPE_FINGER`. This provides a clean input split without
software palm rejection:

| Tool Type        | Action                              |
|------------------|-------------------------------------|
| `TOOL_TYPE_STYLUS` | Draw, erase, select, or move (per tool) |
| `TOOL_TYPE_FINGER` | Pinch-to-zoom, pan, edge swipe navigation |

### Historical Points

The Wacom EMR digitizer batches events. To capture all intermediate points
for smooth strokes, `PadCanvasView` processes `MotionEvent.getHistoricalX/Y`
on every `ACTION_MOVE`, not just the current event coordinates.

### Edge Swipe Navigation

Finger swipes originating from the left or right 8% of the screen trigger
page navigation (previous/next page). Requires a minimum horizontal distance
of 100px. Multi-finger gestures cancel edge swipe detection. Swiping forward
past the last page auto-creates a new page if the current page has strokes.

### Line Snap

When drawing in pen mode, holding the stylus still for 1.5 seconds
activates line snap mode. The stroke is replaced with a straight line
from the original pen-down point to the current position. Moving the
pen continues the straight line. The snap timer is canceled if the pen
moves more than ~5mm (60pt at 300 DPI) from the origin before the
timer fires. This allows drawing straight lines for diagrams without
a separate ruler tool.

## Rendering Strategy

### On-Screen

Three-layer compositing with cached bitmaps:

1. **Grid layer** — cached bitmap at screen resolution, redrawn only when
   zoom, pan, or view size changes. Grid is drawn in screen pixel space
   (not canonical space) with pixel-snapped line positions for perfectly
   uniform squares regardless of zoom level. Uses 1px screen-space lines.

2. **Stroke layer** — screen-resolution backing bitmap. Completed strokes
   are drawn as `Path` objects via the view `Matrix`. New strokes are added
   incrementally (drawn onto the existing bitmap without clearing) to avoid
   full-redraw flicker. The bitmap is fully rebuilt only on zoom/pan changes
   or stroke deletion.

3. **Dynamic layer** — drawn directly on each `onDraw` call in canonical
   space via the view `Matrix`. Includes: in-progress stroke (pen is down),
   line/box previews, selection rectangle and highlights.

Anti-aliasing is disabled on all paint objects for crisp e-ink rendering.

### Viewport

The page always fills the entire visible canvas area:
- Minimum zoom is computed dynamically so the page never appears smaller
  than the viewport in either dimension.
- Pan is clamped so page edges stay at or beyond viewport edges.
- Background is white to eliminate any visible non-page area.

### PDF Export

Uses Android's `PdfDocument` API. `PdfDocument` pages use 1/72-inch units,
so stroke coordinates are scaled by 72/300 = 0.24 during export. A `Matrix`
pre-concatenated with the export canvas handles this. The grid drawing pass
is skipped.

Export flow:
1. Create `PdfDocument`.
2. For each page: add a `PdfDocument.Page` with canonical dimensions,
   draw all strokes using the same `Path`/`Paint` rendering code.
3. Write to a temp file in the app's cache directory.
4. Share via `Intent.ACTION_SEND` with a `FileProvider` URI.

### JPG Export

Single-page export at 300 DPI (full canonical resolution). Creates a
`Bitmap`, renders all strokes (no grid), compresses to JPEG at 95% quality.
Shared via the same `FileProvider` + intent mechanism as PDF.

## Undo/Redo

Command pattern with a depth limit of 50:

| Action               | Execute           | Undo              |
|----------------------|-------------------|--------------------|
| `AddStrokeAction`    | Insert stroke     | Delete stroke      |
| `DeleteStrokeAction` | Delete stroke     | Re-insert stroke   |
| `MoveStrokesAction`  | Offset points     | Restore original points |
| `DeleteMultipleAction`| Delete strokes   | Re-insert strokes  |
| `CopyStrokesAction`  | Duplicate strokes | Delete copies      |

The `UndoManager` maintains two stacks. Performing a new action clears the
redo stack. Each action also persists or deletes from Room as part of
execute/undo.

## Selection

Rectangle selection (initial implementation; lasso selection as a future
upgrade):

1. In select mode, stylus drag draws a selection rectangle.
2. Strokes whose bounding boxes intersect the rectangle are selected.
3. Selected strokes get a visual highlight (translucent overlay + bounding box).
4. Available operations: cut, copy, delete, paste (toolbar buttons appear
   contextually when strokes are selected or clipboard is non-empty).
5. All selection operations are undoable.

## Eraser

Stroke-level eraser (not pixel-level):

1. In erase mode, stylus touch/drag hit-tests against all strokes on the page.
2. Hit test: check stroke bounding box first (fast reject), then check
   point-by-point distance (threshold: ~42 canonical points / ~3.5mm).
3. Hit strokes are deleted immediately (with undo support).

## Startup State Restoration

The app persists the last-opened notebook ID and a flag for whether the page
list was showing in `SharedPreferences` (via `EngPadApp`). On launch:
- If a notebook was previously open, auto-navigate to it.
- If the page list was showing, navigate to the page list on top.
- The editor resumes at the notebook's `lastPageId` (tracked per-notebook in
  the DB).

## E-ink Considerations

Both target devices have e-ink or e-ink-like displays with high refresh latency:

- Minimize animations and transitions.
- Use high-contrast colors (black on white).
- Minimize invalidation regions (invalidate only the bounding box of new
  stroke segments, not the full canvas).
- Consider a manual "refresh" button to force a full-screen redraw to clear
  e-ink ghosting.

## Sync Architecture (Planned)

eng-pad will sync notebooks to an eng-pad-server instance over gRPC:

- **Protocol**: gRPC with protobuf-lite, over TLS.
- **Authentication**: password-based auth to eng-pad-server (not MCIAS — this
  is a personal-use app, not a Metacircular service).
- **Sync model**: manual sync (user-initiated, not automatic). Per-notebook
  sync button and sync-all from the library.
- **Conflict resolution**: last-write-wins based on `updated_at` timestamps,
  with potential for manual resolution in future.
- **Data flow**: push local changes, pull remote changes. Full notebook
  content (metadata + pages + strokes) serialized for transfer.
- **Status tracking**: per-notebook sync state (synced, pending, error)
  displayed as badges in the notebook list.

## Backup/Export Design (Planned)

Notebook backup as a portable zip file:

- **Format**: `notebook_title.engpad.zip` containing:
  - `notebook.json` — notebook metadata (title, page_size, page count)
  - `pages/001.json`, `pages/002.json`, ... — one file per page with
    metadata and strokes array
  - Each stroke: `{penSize, color, style, points: [x0,y0,x1,y1,...]}`
  - Points as JSON float arrays (portable, human-readable)
- **Import**: parse zip, create notebook + pages + strokes in Room DB.
- **Export-all**: single zip containing all notebooks for full backup.
- **Sharing**: via Android share intents (same mechanism as PDF/JPG).

## Source Tree

```
eng-pad/
├── app/
│   ├── build.gradle.kts                              -- Module build config
│   └── src/
│       ├── main/
│       │   ├── AndroidManifest.xml
│       │   ├── kotlin/net/metacircular/engpad/
│       │   │   ├── EngPadApp.kt                      -- Application class, SharedPreferences
│       │   │   ├── MainActivity.kt                   -- Single activity, Compose NavHost
│       │   │   ├── data/
│       │   │   │   ├── db/
│       │   │   │   │   ├── EngPadDatabase.kt         -- Room database (version 3)
│       │   │   │   │   ├── NotebookDao.kt            -- Notebook CRUD
│       │   │   │   │   ├── PageDao.kt                -- Page CRUD + reorder
│       │   │   │   │   ├── StrokeDao.kt              -- Stroke CRUD
│       │   │   │   │   └── Converters.kt             -- Room type converters
│       │   │   │   ├── model/
│       │   │   │   │   ├── Notebook.kt               -- Room entity (+ lastPageId)
│       │   │   │   │   ├── Page.kt                   -- Room entity
│       │   │   │   │   ├── Stroke.kt                 -- Room entity (+ style column)
│       │   │   │   │   └── PageSize.kt               -- Enum: REGULAR, LARGE
│       │   │   │   └── repository/
│       │   │   │       ├── NotebookRepository.kt     -- Notebook operations + rename
│       │   │   │       └── PageRepository.kt         -- Page + stroke ops + reorder
│       │   │   ├── ui/
│       │   │   │   ├── navigation/
│       │   │   │   │   └── NavGraph.kt               -- Routes, auto-restore last notebook
│       │   │   │   ├── notebooks/
│       │   │   │   │   ├── NotebookListScreen.kt     -- Library: list, filter, sort, rename
│       │   │   │   │   └── NotebookListViewModel.kt  -- Notebook list state + rename
│       │   │   │   ├── pages/
│       │   │   │   │   ├── PageListScreen.kt         -- Page grid, drag-to-reorder
│       │   │   │   │   └── PageListViewModel.kt      -- Page list state + reorder
│       │   │   │   ├── editor/
│       │   │   │   │   ├── PadCanvasView.kt          -- Custom View: rendering + input + edge swipe
│       │   │   │   │   ├── EditorScreen.kt           -- Compose wrapper
│       │   │   │   │   ├── EditorViewModel.kt        -- Editor state, page nav, clipboard
│       │   │   │   │   ├── CanvasState.kt            -- Tool, PenSize, LineStyle, zoom/pan
│       │   │   │   │   └── Toolbar.kt                -- Icon-button toolbar with Canvas icons
│       │   │   │   ├── export/
│       │   │   │   │   └── PdfExporter.kt            -- PDF + JPG generation + sharing
│       │   │   │   └── theme/
│       │   │   │       └── Theme.kt                  -- Material3 high-contrast e-ink theme
│       │   │   └── undo/
│       │   │       ├── UndoManager.kt                -- Undo/redo stack
│       │   │       ├── UndoableAction.kt             -- Action interface
│       │   │       ├── StrokeActions.kt              -- Add/delete stroke actions
│       │   │       └── SelectionActions.kt           -- Multi-stroke delete/move/copy
│       │   └── res/
│       │       ├── values/
│       │       │   ├── strings.xml
│       │       │   └── themes.xml
│       │       ├── drawable/                          -- Launcher icons
│       │       ├── mipmap-anydpi/                     -- Adaptive icon
│       │       └── xml/
│       │           └── file_provider_paths.xml        -- FileProvider config
│       └── test/
│           └── kotlin/net/metacircular/engpad/
│               ├── data/
│               │   ├── StrokeBlobTest.kt             -- Float array <-> blob roundtrip
│               │   └── PageSizeTest.kt               -- Page size enum tests
│               └── undo/
│                   └── UndoManagerTest.kt            -- Undo/redo logic
├── build.gradle.kts                                  -- Root build config
├── settings.gradle.kts                               -- Project settings (foojay JDK resolver)
├── gradle.properties                                 -- Gradle properties
├── gradle/
│   └── libs.versions.toml                            -- Version catalog
├── Makefile                                          -- Build targets (build, test, lint, run, devrun)
├── .gitignore
├── CLAUDE.md
├── README.md
├── DESIGN.md                                         -- This file
├── PROJECT_PLAN.md                                   -- Implementation steps
└── PROGRESS.md                                       -- Completion tracking
```