Edge Contract Specification

Version: 0.1 (Draft)
Date: March 2026
Status: Proposal
Depends on: Stroke Format Spec, Visual Primitives Spec
Implements: BOOX Edge, reMarkable Edge, iPad Edge, Web Edge

1. Overview

The Edge Contract defines what any Edge implementation must support to be a valid FreakingGenius "paper" device.

An Edge is dumb by design. It captures strokes, renders primitives, reports its state. It does not interpret math, make pedagogical decisions, or generate audio.

Edge is paper. Paper doesn't think.

1.1 Contract Scope

This spec defines:

• Capability negotiation (what Edge can do)
• Message types (what Edge sends and receives)
• State machine (session lifecycle)
• Behavior requirements (how Edge must behave)

This spec does NOT define:

• Native implementation details (Android, iOS, web specifics)
• UI chrome design (buttons, menus)
• Offline storage internals

1.2 Reference Implementations

2. Capability Model

2.1 Capability Declaration

At session start, Edge sends its capabilities to Tutor (via Bridge):

{
  "type": "CAPABILITIES",
  "device": {
    "id": "dev_abc123",
    "platform": "boox",
    "model": "Tab Ultra C",
    "edgeVersion": "1.0.0",
    "protocolVersion": 1
  },
  "display": {
    "width": 2480,
    "height": 1860,
    "colorDepth": 16,
    "refreshRate": "medium",
    "colorSupport": true
  },
  "input": {
    "stylus": true,
    "stylusPressure": true,
    "stylusTilt": true,
    "touch": true,
    "samplingRate": 120
  },
  "features": {
    "audio": false,
    "camera": false,
    "haptics": false,
    "offlineStorage": "2GB"
  }
}

2.2 Capability Fields

Device Info

Display

Input

Features

2.3 Capability Negotiation

┌─────────┐                    ┌─────────┐
│  Edge   │                    │  Tutor  │
└────┬────┘                    └────┬────┘
     │                              │
     │   CAPABILITIES               │
     │─────────────────────────────►│
     │                              │
     │   SESSION_CONFIG             │
     │◄─────────────────────────────│
     │                              │
     │   (session active)           │

Tutor (via Bridge) responds with configuration based on capabilities:

{
  "type": "SESSION_CONFIG",
  "sessionId": "sess_xyz789",
  "renderMode": {
    "color": true,
    "animations": false,
    "refreshStrategy": "partial"
  },
  "strokeConfig": {
    "batchIntervalMs": 200,
    "format": "binary",
    "includePressure": true
  },
  "features": {
    "hintsEnabled": true,
    "guidesEnabled": true
  }
}

3. Message Protocol

3.1 Message Envelope

All messages wrapped in standard envelope:

{
  "version": 1,
  "timestamp": 1711670400000,
  "type": "MESSAGE_TYPE",
  "payload": { ... }
}

3.2 Messages: Edge → Tutor

CAPABILITIES

Sent at session start. See section 2.1.

STROKE_BATCH

Stroke data per Stroke Format Spec.

{
  "type": "STROKE_BATCH",
  "payload": {
    "sessionId": "sess_xyz789",
    "seq": 42,
    "strokes": [ ... ],
    "partial": { ... }
  }
}

GESTURE

User gesture detected.

{
  "type": "GESTURE",
  "payload": {
    "gesture": "undo",
    "timestamp": 1711670450000
  }
}

HEARTBEAT

Periodic status (every 30s).

{
  "type": "HEARTBEAT",
  "payload": {
    "sessionId": "sess_xyz789",
    "battery": 78,
    "connectivity": "strong",
    "activeZone": "work_zone",
    "strokeCount": 142,
    "lastActivityMs": 1200
  }
}

ZONE_ACTIVITY

Fired when student enters/exits an input zone.

{
  "type": "ZONE_ACTIVITY",
  "payload": {
    "zoneId": "answer_zone",
    "action": "enter",
    "timestamp": 1711670500000
  }
}

ERROR

Edge encountered an error.

{
  "type": "ERROR",
  "payload": {
    "code": "RENDER_FAILED",
    "message": "Failed to render MATH_BLOCK: unsupported format",
    "primitiveId": "math_001"
  }
}

3.3 Messages: Tutor → Edge

SESSION_CONFIG

Session configuration. See section 2.3.

LOAD_EXERCISE

Load new exercise content.

{
  "type": "LOAD_EXERCISE",
  "payload": {
    "exerciseId": "ex_4521",
    "primitives": [ ... ],
    "clearStrokes": true
  }
}

PRIMITIVE

Single primitive command.

{
  "type": "PRIMITIVE",
  "payload": {
    "type": "HIGHLIGHT",
    "id": "hl_001",
    ...
  }
}

PRIMITIVE_BATCH

Multiple primitives at once.

{
  "type": "PRIMITIVE_BATCH",
  "payload": {
    "primitives": [ ... ]
  }
}

CLEAR

Clear primitives or strokes.

{
  "type": "CLEAR",
  "payload": {
    "target": "annotations"
  }
}

STROKE_ACK

Acknowledge received strokes.

{
  "type": "STROKE_ACK",
  "payload": {
    "ackSeq": 42
  }
}

Edge can discard buffered batches ≤ ackSeq.

SESSION_END

End the session.

{
  "type": "SESSION_END",
  "payload": {
    "reason": "completed",
    "summary": {
      "duration": 2700,
      "exercisesCompleted": 5,
      "strokeCount": 487
    }
  }
}

4. Session State Machine

                    ┌─────────────┐
                    │   IDLE      │
                    │  (app open, │
                    │ not paired) │
                    └──────┬──────┘
                           │ Pairing initiated
                           ▼
                    ┌─────────────┐
                    │  PAIRING    │
                    │             │
                    └──────┬──────┘
                           │ CAPABILITIES sent, SESSION_CONFIG received
                           ▼
                    ┌─────────────┐
                    │   ACTIVE    │◄─────────────────────┐
                    │             │                      │
                    │ • Streaming │  LOAD_EXERCISE       │
                    │   strokes   │──────────────────────┘
                    │ • Rendering │
                    │   primitives│
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
       ┌──────────┐ ┌──────────┐ ┌──────────┐
       │  PAUSED  │ │RECONNECT │ │  ENDED   │
       │          │ │          │ │          │
       │ (user    │ │ (conn    │ │ (session │
       │  paused) │ │  lost)   │ │  over)   │
       └────┬─────┘ └────┬─────┘ └──────────┘
            │            │
            │  Resume    │  Connection restored
            └────────────┴───────► ACTIVE

4.1 State Descriptions

4.2 Reconnection Behavior

When connection drops:

1. Edge enters RECONNECTING state
2. Continue capturing strokes to local buffer
3. Attempt reconnect every 2s (exponential backoff to 30s max)
4. On reconnect:
   • Re-send CAPABILITIES
   • Receive SESSION_CONFIG (with resume: true)
   • Replay buffered strokes
5. If offline > 5 minutes: prompt user, offer to save locally

5. Rendering Requirements

5.1 Content Layer

Edge MUST:

• Render all Content primitives (TEXT, MATH_BLOCK, IMAGE, LINE, BOX, DIVIDER)
• Support at least asciimath format for MATH_BLOCK
• Render INPUT_ZONE borders when showBorder: true
• Render INPUT_GUIDE patterns (ruled, grid)

Edge SHOULD:

• Support latex format for MATH_BLOCK
• Optimize rendering for device (e.g., e-ink refresh batching)

5.2 Stroke Layer

Edge MUST:

• Render strokes as smooth paths
• Honor pressure data for stroke width (if supported)
• Support undo/redo of strokes
• Distinguish PEN vs ERASER tool

Edge SHOULD:

• Minimize latency from stylus to visible ink (<20ms)
• Apply palm rejection
• Support tilt for natural stroke shading

5.3 Annotation Layer

Edge MUST:

• Render all Annotation primitives
• Apply intent-based styling (focus/warning/error/success)
• Adapt to capability (color vs grayscale)
• Render annotations above strokes

Edge SHOULD:

• Animate PULSE appropriately for display type
• Auto-dismiss HINT_BUBBLE on tap (optional based on config)

5.4 Refresh Strategy

For e-ink displays:

6. Stroke Capture Requirements

6.1 Sampling

Edge MUST:

• Sample at ≥60Hz (≥120Hz preferred)
• Include timestamp per point
• Include pressure if hardware supports
• Capture in device coordinates, convert to normalized

6.2 Batching

Edge MUST:

• Batch strokes per SESSION_CONFIG batchIntervalMs
• Send partial stroke data for in-progress strokes
• Include sequence number for ordering
• Buffer unsent batches during connection issues

6.3 Gesture Detection

Edge MUST detect and report:

• undo (platform-standard gesture or button)
• submit (explicit "done" action)

Edge SHOULD detect:

• help (request hint)
• next / previous (exercise navigation if enabled)

7. Offline Behavior

7.1 Minimum Offline Capability

Edge MUST:

• Continue capturing strokes when offline
• Buffer up to 30 minutes of stroke data
• Display last loaded exercise content
• Show clear offline indicator to user

7.2 Extended Offline (Future)

Edge MAY:

• Cache multiple exercises for offline work
• Store completed work for later sync
• Provide degraded experience without Tutor

8. UI Requirements

8.1 Required UI Elements

8.2 Optional UI Elements

8.3 UI Principles

• Minimal chrome: Maximize writing area
• Paper feel: UI should be unobtrusive
• No distractions: No notifications, no other apps visible
• Clear affordances: Obvious how to undo, submit, get help

9. Security Requirements

9.1 Communication

• All Edge ↔ Tutor communication over TLS (WSS or HTTPS)
• Session tokens expire after 24 hours
• Device pairing requires explicit user action

9.2 Local Storage

• Stroke data encrypted at rest
• No PII stored on device beyond session
• Clear local data on unpair

9.3 Privacy

• Edge does not capture audio or camera without explicit feature flag
• Stroke data is educational record — treat accordingly
• Parent/guardian consent required for minor users (handled by Cloud, not Edge)

10. Testing Requirements

Edge implementations must pass:

10.1 Capability Tests

• Sends valid CAPABILITIES on connect
• Handles SESSION_CONFIG correctly
• Reports accurate display/input capabilities

10.2 Stroke Tests

• Captures strokes at declared sampling rate
• Batches correctly per config
• Includes valid timestamps
• Handles pressure (if declared)
• Sends partial strokes

10.3 Rendering Tests

• Renders all Content primitives
• Renders MATH_BLOCK (at least asciimath)
• Renders all Annotation primitives
• Applies intent styling correctly
• Handles CLEAR commands

10.4 Session Tests

• Reconnects after connection drop
• Replays buffered strokes on reconnect
• Handles SESSION_END gracefully
• Reports HEARTBEAT periodically

10.5 Edge Cases

• Handles malformed primitives gracefully
• Survives rapid primitive updates
• Works with low battery
• Works on slow WiFi

11. Implementation Checklist

For each new Edge platform:

Phase 1: Core

• WebSocket connection to Tutor
• CAPABILITIES exchange
• Stroke capture and batching
• Basic stroke rendering

Phase 2: Content

• TEXT primitive
• MATH_BLOCK primitive (asciimath)
• INPUT_ZONE primitive
• LINE, BOX, DIVIDER primitives

Phase 3: Annotation

• HIGHLIGHT with intent colors
• UNDERLINE, CIRCLE, ARROW
• MARK (checkmark/X)
• HINT_BUBBLE

Phase 4: Polish

• Gesture detection
• Reconnection handling
• Offline buffering
• Performance optimization

Appendix A: Protocol Version History

Appendix B: Message Type Reference

Edge → Tutor

Tutor → Edge

Appendix C: Error Codes

This completes Phase 1: Foundation specs. Next: Bridge Protocol (Phase 2).