Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
name: test
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
env:
ELECTRON_SKIP_BINARY_DOWNLOAD: "1"
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm test
- run: npm run smoke
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
node_modules/
dist/
release/
.smartspectra-key
*.log
.DS_Store
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 Subomi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
65 changes: 65 additions & 0 deletions PRIVACY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Consent and data handling

Heartwritten reads your face through your camera to estimate your heart rate,
pulse wave, breathing and smiles while you write a letter. This page says what
happens to that data.

## Before anything starts

The app opens on a consent screen. The camera stays off until you tick
"I'm the only person on camera, and I agree to this" and press
**Turn on the camera**. A red dot shows while the camera is on, and
**Stop camera** turns it off at any point; the rest of the letter then
carries no heartbeat.

You choose, before you start:

- whether the reader sees where you smiled (on by default)
- whether the reader sees words you typed and took back (off by default)
- whether the SmartSpectra SDK sends telemetry to Presage (off by default)

## What is kept

- **Kept:** the letter's text, when each character was typed, and numbers
sampled four times a second: heart rate, a breathing value and (if you
allow it) a smile score. Six seconds of the pulse wave for the seal.
- **Never kept:** video, photos, frames or anything that shows your face.
Words you delete are dropped unless you chose to share them.

## Where it goes

- **While you write**, nothing is saved to disk. The letter exists only in
the app's memory.
- **The SmartSpectra SDK** measures on your computer. Presage's documentation
says all metric computation runs on-device and the SDK calls Presage's
service only to check the API key, so it needs a network connection while
measuring. Presage says its telemetry does not include frames or vitals. Telemetry
is off in Heartwritten unless you turn it on; if you do, Presage receives
session summaries and device details linked to your API key.
- **When you seal it**, the letter is packed into a token that lives in the link
(after the `#`, which browsers don't send to servers) or in an HTML file you
save. Heartwritten has no server and no account. Nobody has the letter until
you send the link or file to them.
- **The reader page** can't send anything: its Content Security Policy blocks
every network request, and it loads nothing from anywhere else.

## How long it lasts, and deleting it

- Closing the writer forgets the letter unless you copied the link or saved the
file.
- A sealed letter lasts as long as the link or file does. Delete the file, or
the message you sent the link in, to delete the letter. Anyone you've sent it
to keeps their copy, as with any letter.
- Heartwritten stores nothing else. Your API key stays in the file or
environment variable you put it in.

## AI

Heartwritten uses no AI model of its own. The physiological estimates come from
the SmartSpectra SDK.

## Not medical

Heart rate and breathing are camera estimates for feeling, not medicine.
Heartwritten makes no diagnosis, gives no health advice and isn't for
monitoring anyone. Only write with your own face on camera.
119 changes: 118 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1 +1,118 @@
# heartwritten
# Heartwritten

**Letters that carry the heartbeat you wrote them with.**

You write a letter at your desk. While you type, your laptop camera reads your
heart rate, pulse wave, breathing and smiles with the
[Presage SmartSpectra SDK](https://physiology.presagetech.com). When you're
done, you seal it with a wax seal pressed from your own pulse wave.

The person you send it to opens the envelope and watches the letter being
written again at your pace: the pauses where you thought, the sentence you
rushed, the ink warming where your heart sped up, the page rising and falling
with your breath, a soft glow where you smiled. At the end they see where your
heart was quickest and where it was steadiest.

Nothing goes to a server. A sealed letter lives inside its link (in the part
after `#`, which browsers never send) or inside a single HTML file.

## Try it

You need Node 20 or newer and a webcam.

```
npm install
npm run start:sim
```

`start:sim` runs the whole app with simulated signals, so you can try it with
no key. Letters written this way are marked as samples, everywhere.

To read the real thing:

1. Get an API key from [physiology.presagetech.com](https://physiology.presagetech.com).
2. Put it in a file called `.smartspectra-key` in this folder (it's git-ignored),
or set `SMARTSPECTRA_API_KEY` in your shell.
3. Check the SDK and key work: `npm run smoke`
4. Write a letter: `npm start`

The SDK ships native libraries for macOS on Apple silicon, Linux (x64 and arm64)
and Windows x64. Measurement runs on your computer; the SDK needs a network connection
only so Presage can check the key.

To see a finished letter without the app, run `npm run sample` and open
`dist/sample-letter.html` in a browser.

## Sharing by link

The writer can save any letter as a file. To share by link instead, host the
reader page somewhere static and tell the writer its address:

```
npm run build # makes dist/reader/index.html, one self-contained file
```

Deploy `dist/reader` anywhere static (a `vercel.json` is included), then put
the address in `heartwritten.config.json`:

```json
{ "readerUrl": "https://your-reader.example" }
```

or set `HEARTWRITTEN_READER_URL`. The reader has a Content Security Policy of
`default-src 'none'; connect-src 'none'`, so it can't send anything anywhere,
and the letter in the `#` part of the link never reaches the host's logs.

## How it responds to human signals

| Signal (SmartSpectra) | While writing | In the letter |
| --- | --- | --- |
| Pulse rate (`cardio.pulseRate`, stable values only) | Live number and a trace drawn in the ink colour | Ink colour per character: calm navy near the writer's own median, warming toward red as the heart quickens, cooling as it settles. A beating heart in the margin keeps time. The closing card finds the quickest and steadiest sentences. |
| Pulse wave (`cardio.arterialPressureTrace`) | Live trace | The wax seal: six seconds of the wave, wrapped into a ring and pressed into wax. Every seal is different. |
| Breathing (`breathing.upperTrace`, `breathing.rate`) | Breaths a minute | The paper rises and falls with the writer's breathing as it replays. |
| Smiles (`face.expression`, happy) | A small mark lights up | Words written while smiling glow softly. Optional. |
| Validation status | Plain-language hints: "move a little closer or further", "a little more light, please" | |

Typing is recorded as timed edits, so the replay keeps the real rhythm. Long
pauses (over eight seconds) are shortened in the replay but noted in the margin.
Words you delete are dropped from the letter unless you choose to share them.

## Privacy and consent

The consent screen comes before the camera turns on, and says plainly what is
read, what is kept and where it goes. See [PRIVACY.md](PRIVACY.md) for the full
data handling, including the SDK's telemetry, which is off unless you turn it on.

Heartwritten is for feeling, not medicine. Heart rate and breathing are camera
estimates. It makes no diagnosis and gives no health advice.

## How it's built

```
app/main.cjs Electron main: window, camera permission, SDK IPC, key lookup
src/writer/ The writing desk (consent → write → seal)
sdk-source.js SmartSpectra renderer SDK, events decoded into metrics
src/reader/ The reader, built into one self-contained HTML file
src/shared/
vitals.js Turns SDK metrics packets into steady pulse, breath and smile values
recorder.js Records timed edits and 4 Hz vitals while you write
letter-format.js Packs a letter into a compact, deflated, URL-safe token
playback.js Replays the edits and maps the heart to ink
summary.js Quickest and steadiest sentences, smiles, words taken back
seal.js Draws the wax seal from the pulse wave
sim-source.js Simulated SDK output for development and tests
test/ node --test: the core, plus the built pages in jsdom
```

`npm test` builds everything and runs 25 tests, including the reader replaying
a full letter and the writer going from consent to a sealed letter in
simulated mode.

The Electron wiring follows Presage's `electron-quickstart` sample: the main
process binds the SDK's IPC, the preload exposes it, and the renderer runs
`SmartSpectraSDK` with the camera.

## License

MIT for this code (see [LICENSE](LICENSE)). The SmartSpectra SDK has its own
license from Presage Technologies.
97 changes: 97 additions & 0 deletions app/main.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
// main.cjs
// Electron main process for the Heartwritten writer.
'use strict';

const fs = require('fs');
const path = require('path');
const { app, BrowserWindow, ipcMain, session } = require('electron');

const ROOT = path.join(__dirname, '..');
const DIST = path.join(ROOT, 'dist');

// Packaged builds load the SDK's native runtime from resources/smartspectra.
if (app.isPackaged && !process.env.SMARTSPECTRA_CAPI_PATH) {
const LIB = { darwin: 'libsmartspectra_capi.dylib', win32: 'smartspectra_capi.dll', linux: 'libsmartspectra_capi.so' }[process.platform];
if (LIB) process.env.SMARTSPECTRA_CAPI_PATH = path.join(process.resourcesPath, 'smartspectra', LIB);
}

const SIMULATE = process.env.HEARTWRITTEN_SIMULATE === '1';
// Where shared links open. Deploy dist/reader anywhere static and set this.
const READER_URL = process.env.HEARTWRITTEN_READER_URL || readConfig().readerUrl || '';

function readConfig() {
try { return JSON.parse(fs.readFileSync(path.join(ROOT, 'heartwritten.config.json'), 'utf8')); } catch { return {}; }
}

// The key never ships in the repo: it comes from the environment or a local
// file that .gitignore keeps out of git.
function apiKey() {
if (process.env.SMARTSPECTRA_API_KEY) return process.env.SMARTSPECTRA_API_KEY.trim();
for (const p of [path.join(ROOT, '.smartspectra-key'), path.join(app.getPath('userData'), 'smartspectra-key')]) {
try { const k = fs.readFileSync(p, 'utf8').trim(); if (k) return k; } catch { /* not there */ }
}
return '';
}

let mainWindow = null;

function createWindow() {
mainWindow = new BrowserWindow({
width: 1040,
height: 860,
minWidth: 720,
backgroundColor: '#e7dcc7',
title: 'Heartwritten',
webPreferences: {
preload: path.join(DIST, 'preload.cjs'),
contextIsolation: true,
sandbox: true,
nodeIntegration: false,
},
});
if (!SIMULATE) {
const { bindSmartSpectraIpc } = require('@smartspectra/node-sdk/main');
bindSmartSpectraIpc(mainWindow);
}
lockDown(mainWindow);
mainWindow.loadFile(path.join(DIST, 'writer', 'index.html'));
}

function lockDown(win) {
win.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
win.webContents.on('will-navigate', (e) => e.preventDefault());
}

// The reader opens in its own window with no preload and no camera.
function openPreview(token) {
if (!/^v1\.[A-Za-z0-9_-]+$/.test(token)) return false;
const win = new BrowserWindow({
width: 900, height: 900, title: 'Your letter, as they will see it', backgroundColor: '#e9dfcc',
webPreferences: { contextIsolation: true, sandbox: true, nodeIntegration: false },
});
win.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
win.loadFile(path.join(DIST, 'reader', 'index.html'), { hash: token });
return true;
}

app.whenReady().then(() => {
// Camera only, video only, only for the writer page.
session.defaultSession.setPermissionRequestHandler((wc, permission, callback, details) => {
const url = (details && details.requestingUrl) || (wc && wc.getURL()) || '';
const media = (details && details.mediaTypes) || [];
const ok = permission === 'media' && media.length === 1 && media[0] === 'video'
&& url.startsWith('file://') && url.includes('/dist/writer/')
&& mainWindow && wc === mainWindow.webContents;
callback(ok);
});

ipcMain.handle('hw:config', () => ({ hasKey: !!apiKey(), simulate: SIMULATE, readerUrl: READER_URL }));
ipcMain.handle('hw:api-key', (e) => (mainWindow && e.sender === mainWindow.webContents ? apiKey() : ''));
ipcMain.handle('hw:preview', (_e, token) => openPreview(token));

createWindow();
app.on('activate', () => { if (BrowserWindow.getAllWindows().length === 0) createWindow(); });
});

app.on('window-all-closed', () => { if (process.platform !== 'darwin') app.quit(); });

25 changes: 25 additions & 0 deletions docs/demo-script.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Demo video script (about 90 seconds)

Record on your Mac with a real key, good light on your face and the room quiet.
Screen-record the app, with a small picture-in-picture of your face only for
shot 2. Write a short, real letter to someone (about 4 sentences) with one
moment that actually moves you, and one line that makes you smile.

| # | Time | On screen | Voice-over |
| --- | --- | --- | --- |
| 1 | 0:00–0:08 | A typed message on a phone, then a scanned handwritten letter with a crossed-out word | "Handwritten letters told you how they felt to write. Typed ones don't." |
| 2 | 0:08–0:18 | Heartwritten consent screen; tick agree; camera on; live heart trace and bpm settle | "Heartwritten reads your heartbeat, breathing and smiles through the webcam, with Presage SmartSpectra. Nothing is saved, and nothing goes to a server." |
| 3 | 0:18–0:40 | Write the letter. Let the bpm visibly change at the emotional line. Smile once. Pause for a few seconds before the last line. | (Quiet. Let the typing and the live heart carry it.) |
| 4 | 0:40–0:48 | Press **Seal it with my heartbeat**; the wax seal presses in | "You seal it with your own pulse wave. No two seals are the same." |
| 5 | 0:48–1:15 | Open the link in a browser as the recipient. Tap the seal, it cracks. The letter writes itself: ink warming at the emotional line, the margin heart beating, a glow on the smiling words, "paused 9 seconds" in the margin | "They watch it written again, at your pace. The ink warms where your heart sped up. The page breathes with you." |
| 6 | 1:15–1:25 | The closing card: quickest and steadiest sentences | "And at the end, where your heart was quickest, and where it was steadiest." |
| 7 | 1:25–1:30 | The seal again, with the line "lives only in its link" | "Heartwritten. Letters that carry your heartbeat." |

Tips:

- Keep the camera picture out of shot 5: the letter is the point, and it shows
the recipient never sees your face.
- If the heart barely moves while writing, read the letter aloud once first, or
write about something you care about. Don't fake it with exercise; judges
will see the ink jump.
- Use the 1× replay speed for the emotional part, then skip to the end.
Loading
Loading