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
35 changes: 26 additions & 9 deletions PRIVACY.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,26 +22,43 @@ You choose, before you start:

- **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.
allow it) a smile score. Six seconds of the pulse wave for the seal. The
names you type in "To" and "From", and the date you sealed it (the day
only, no time of day).
- **Never kept:** video, photos, frames or anything that shows your face.
Words you delete are dropped unless you chose to share them.
Words you delete are dropped unless you chose to share them. If you turn
"Show where I smiled" off, smiles are not requested from the SDK at all.

## Where it goes

- **While you write**, nothing is saved to disk. The letter exists only in
the app's memory.
- **While you write**, Heartwritten saves nothing to disk. The letter exists
only in the app's memory. Nothing is recorded until you type the first
character.
- **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.
session summaries and device details linked to your API key. The SDK is
Presage's own code, so what it sends is Presage's statement, not something
Heartwritten can enforce. Heartwritten's own code makes no network requests.
- **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.
save. Heartwritten has no backend, no database and no account. Nobody has
the letter until you send the link or file to them.
- **The reader page** is one static HTML file. When someone opens a link, their
browser fetches that page from wherever it is hosted (by default
heartwritten.vercel.app), and the host sees what any website sees: an IP
address, a browser and a time. It does not see the letter, because the
letter is in the `#` part of the link. Once loaded, the page can't send
anything: its Content Security Policy blocks scripts from making network
requests, it loads nothing from anywhere else, and it sets no cookies and
uses no browser storage. A letter saved as a file opens with no network at
all.
- **The app itself** is built on Electron (Chromium). On Windows and Linux,
Chromium may download a spelling dictionary the first time you type; the
spell check itself runs on your computer. On macOS it uses the system's own
spell checker.

## How long it lasts, and deleting it

Expand Down
33 changes: 23 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,9 @@ 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.
The letter never 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.
There is no account and no database.

## Try it

Expand All @@ -26,19 +27,27 @@ 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.
no key and no camera. Letters written this way are marked as samples,
everywhere. The first start downloads the Electron runtime (about 100 MB), so
give it a minute.

`npm test` runs the tests and needs no key either.

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`
3. Check the SDK loads and the key is found: `npm run smoke`. It says where it
found the key and never prints it. Presage checks the key itself when a
measurement starts, so to test that too, pass a short video of a face:
`npm run smoke -- path/to/face-clip.mp4`
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.
and Windows x64. Heartwritten has been run on macOS on Apple silicon only.
Measurement runs on your computer. Presage's documentation says the SDK needs a
network connection only so Presage can check the key.

To see a finished letter without the app, open the sample at
https://heartwritten.vercel.app/sample, or run `npm run sample` and open
Expand All @@ -63,8 +72,10 @@ by default. To host your own, deploy `dist/reader` anywhere static (a
```

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.
`default-src 'none'; connect-src 'none'`, so once it has loaded it can't send
anything anywhere. Whoever hosts the page sees an ordinary page request (an IP
address and a browser), as any website does, but the letter in the `#` part of
the link never reaches the host or its logs.

## How it responds to human signals

Expand All @@ -87,12 +98,14 @@ 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.
estimates. It makes no diagnosis, gives no health advice and isn't for
monitoring anyone.

## How it's built

```
app/main.cjs Electron main: window, camera permission, SDK IPC, key lookup
scripts/ Build, the sample letter, and the SDK load check (`npm run smoke`)
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
Expand All @@ -108,7 +121,7 @@ src/shared/
test/ node --test: the core, plus the built pages in jsdom
```

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

Expand Down
5 changes: 4 additions & 1 deletion docs/demo-script.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Demo video script (about 90 seconds)

The shot-by-shot version, with capture settings and DEV's embed rules, is in
[shot-list.md](shot-list.md).

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
Expand All @@ -8,7 +11,7 @@ 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." |
| 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 while you write, and the letter never 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." |
Expand Down
Loading
Loading