Skip to content
Open
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
6 changes: 6 additions & 0 deletions PRIVACY.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,12 @@ You choose, before you start:
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.
- **Link previews.** If you paste a letter's link into a chat app that draws
link previews, that app fetches the reader page and its preview picture to
draw one, as it would for any link. It asks for the address without the `#`
part, so it gets the same page everyone gets and not the letter. The
preview shows a general picture and title, never anything from your letter.
The reader page itself never loads that picture.
- **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
Expand Down
82 changes: 69 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,11 @@ 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.
rushed. Down the left margin of the paper runs a strip of chart paper with
your heartline on it, drawn beside each line as it is written. Where your
heart sped up the line stands taller and the ink warms and feathers; where
you smiled there is a pencil stroke under the words. A postscript says where
your heart was quickest and where it was steadiest.

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.
Expand Down Expand Up @@ -72,24 +74,74 @@ 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 once it has loaded it can't send
anything anywhere. Whoever hosts the page sees an ordinary page request (an IP
`default-src 'none'; connect-src 'none'` (fonts and images may only come from
inside the file itself), 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

| Signal (SmartSpectra) | While writing | In the letter |
| --- | --- | --- |
| Pulse rate (`cardio.pulseRate`, stable values only) | Live number, and each word takes its ink as you type it | Ink colour per character: iron-gall blue-black near the writer's own median, warming through claret to vermilion as the heart quickens, cooling to a clear blue-black as it settles. A pulse in the margin keeps time, and a heartline under the signature draws the whole letter's heart rate. The postscript 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. |
| Pulse rate (`cardio.pulseRate`, stable values only) | The same strip, live: the figure at the line you are on, the heartline growing beside your words, and each word taking its ink as you type it | The margin heartline: a pulse trace down a strip of chart paper bound into the left of the sheet, each line of writing beside the stretch drawn while it was written. Beats stand taller, closer and warmer where the heart was quicker, and the line goes quiet at a long pause. The live figure rides at the pen's tip with a mark that beats in time. Ink colour per character: iron-gall blue-black near the writer's own median, warming through claret to vermilion and feathering into the paper as the heart quickens, cooling to a clear blue as it settles. The postscript finds the quickest and steadiest sentences. |
| Pulse wave (`cardio.arterialPressureTrace`) | The live pulse wave at the top of the strip | 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 | A faint wash on the margin strip swells and ebbs with the writer's breathing as it replays. |
| Smiles (`face.expression`, happy) | A small mark, and a pencil stroke under the words | A hand-drawn pencil stroke under the words written while smiling. 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.
pauses (over eight seconds) are shortened in the replay but pencilled in the
right margin ("paused 9 seconds"). Words you delete are dropped from the
letter unless you choose to share them.

A letter keeps the heart rate four times a second, not every beat. The
heartline is drawn from that rate: the spacing and height of its beats follow
it, so it shows how fast the heart was going, not each beat as it happened.

## How it looks

A letter on a desk at night, with its heartline in the margin. Screenshots are
in [docs/screens](docs/screens) (the `margin-` files).

- The sheet fits the letter. It comes out of the envelope folded in thirds,
opens to its first fold and grows as the writing does.
- One typeface, [Literata](src/fonts/README.md) (SIL Open Font License 1.1),
with small capitals and old-style figures for labels and numbers. Two small
font files are built into the reader page itself, so it still loads nothing
from anywhere.
- The front page at https://heartwritten.vercel.app is itself a letter to the
visitor, written the same way, with a scripted heartbeat that is labelled as
a demonstration.
- The first time the ink warms, a pencil note in the margin says what that
means, once.
- The camera reports in at the top of the writer's margin strip, where the
live pulse will be: waiting for permission, looking for your face, asking
for more light, finding your pulse, reading. If it stops, the strip says so
and you can keep writing.
- After sealing you see the envelope as it will arrive, and copying the link
is confirmed in words.
- The reader's icon is inside the page, and `og.png` beside it is the picture
chat apps show when a link is pasted. Both were made from the reader
itself; nothing is loaded from another site.

## The writer in a browser

The writer is an Electron app today because the SmartSpectra SDK it uses runs
there. Its page is written so it can also be served as a web page:

- `dist/writer` is plain HTML, CSS and one script, laid out for a laptop and
for a phone (390 px wide). It only touches Electron through an optional
`window.heartwritten` bridge; without the bridge it runs on simulated
signals and says so.
- Signals reach the desk through one small interface (`start()`, `stop()`
and the events `stream`, `validationStatus`, `metrics`, `notice`, `error`).
`SOURCES` in `src/writer/writer.js` lists the two there are: the simulator
and the Electron SDK. A browser source would be a third entry.
- What a web version still needs: that browser source and whatever it talks
to, a place to serve the page (`/write`), a consent line that says where
the measuring happens if it is no longer on the writer's own computer, and
an update to [PRIVACY.md](PRIVACY.md) to match.

## Privacy and consent

Expand All @@ -116,12 +168,16 @@ src/shared/
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
heartline.js Draws the letter's heart rate as one line of ink
heartline.js Draws the margin heartline from the heart rate, line by line
sheet.js The sheet on the page: ink runs, the strip, folds (shared by reader and writer)
sheet.css The paper, the strip, the ink and the type (shared by reader and writer)
composeLetter.js Writes a letter from a script: the sample and the front page
src/fonts/ Literata, cut down to two small files, and its licence
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 28 tests, including the reader replaying
`npm test` builds everything and runs 41 tests, including the reader replaying
a full letter and the writer going from consent to a sealed letter in
simulated mode.

Expand Down
4 changes: 2 additions & 2 deletions app/main.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ function createWindow() {
width: 1040,
height: 860,
minWidth: 720,
backgroundColor: '#e7dcc7',
backgroundColor: '#13100e',
title: 'Heartwritten',
webPreferences: {
preload: path.join(DIST, 'preload.cjs'),
Expand All @@ -66,7 +66,7 @@ function lockDown(win) {
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',
width: 900, height: 900, title: 'Your letter, as they will see it', backgroundColor: '#13100e',
webPreferences: { contextIsolation: true, sandbox: true, nodeIntegration: false },
});
win.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
Expand Down
4 changes: 2 additions & 2 deletions docs/demo-script.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ moment that actually moves you, and one line that makes you smile.
| 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." |
| 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." |
| 5 | 0:48–1:15 | Open the link in a browser as the recipient. Tap the seal, it cracks. The letter writes itself: the heartline drawing down the margin strip beside each line, standing taller and turning red at the emotional line as the ink warms, the figure at the pen's tip, a pencil stroke under the smiling words, "paused 9 seconds" in the right margin | "They watch it written again, at your pace. That line in the margin is your heartbeat. The ink warms where your heart sped up." |
| 6 | 1:15–1:25 | The postscript at the foot of the letter: "P.S.", with the 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:
Expand Down
18 changes: 9 additions & 9 deletions docs/dev-post.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,14 @@ You write a letter on your laptop. While you type, SmartSpectra reads your pulse
The person you send it to taps the seal, it cracks, and they watch your letter being written again at your real pace:

- the **ink warms** from blue-black through claret to vermilion where your heart sped up, and cools again as you calmed down
- a small **heart in the margin beats** at your rate, sentence by sentence
- the **paper rises and falls** with your breathing
- words you wrote **while smiling glow**
- **pauses** stay in, and the long ones are noted in the margin beside the line ("paused 14 seconds")
- under your signature, a **heartline** draws your whole heart rate across the letter
- a **heartline runs down the margin**, on a strip of chart paper bound into the letter, drawn beside each line as it is written: taller, tighter and warmer where your heart was quicker, with the figure and a beating mark at the pen's tip
- the quick-hearted words **feather** a little into the paper, and the calm ones stay crisp
- a faint wash on the strip **swells and ebbs** with your breathing
- words you wrote **while smiling** get a pencil stroke under them
- **pauses** stay in, and the long ones are pencilled in the margin beside the line ("paused 9 seconds")
- if you allow it, they see the words you **typed and took back**

At the end, a card shows where your heart was quickest and where it was steadiest, with the sentences.
The letter ends with a postscript: where your heart was quickest and where it was steadiest, with the sentences.

There's no backend, no database and no account. A sealed letter lives entirely inside its link (in the part after `#`, which browsers never send anywhere) or in a single HTML file you can attach to an email.

Expand All @@ -51,10 +51,10 @@ Every signal changes something you can see or hold in the finished letter. None

| SmartSpectra signal | What it becomes |
| --- | --- |
| `cardio.pulseRate` (stable readings only) | The colour of each character's ink, measured against *your own* median for that letter, so a writer with a slow heart and one with a quick heart both get a full range. It also sets the beat of the margin heart, and finds the quickest and steadiest sentences. |
| `cardio.pulseRate` (stable readings only) | The colour of each character's ink, measured against *your own* median for that letter, so a writer with a slow heart and one with a quick heart both get a full range. It also draws the heartline down the margin, sets the beat of the mark at the pen's tip, and finds the quickest and steadiest sentences. |
| `cardio.arterialPressureTrace` | The wax seal. Six seconds of the pulse wave, wrapped into a ring around your initial. |
| `breathing.upperTrace`, `breathing.rate` | The page breathing during replay. |
| `face.expression` (happy) | The glow on words you wrote smiling. Optional, and it's the only face metric I request. |
| `breathing.upperTrace`, `breathing.rate` | A faint wash on the margin strip that swells and ebbs during replay. |
| `face.expression` (happy) | The pencil stroke under words you wrote smiling. Optional, and it's the only face metric I request. |
| Validation status | Gentle hints while you write: "move a little closer or further", "a little more light, please". |

A few things I cared about:
Expand Down
Binary file added docs/screens/margin-after-envelope.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-front-end.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-front.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-phone-10s.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-phone-end.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-phone-envelope.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-phone-front-end.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-phone-front.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-phone-mid.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-phone-writer-write.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-replay-10s.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-replay-end.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-replay-mid.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-writer-consent.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-writer-ready.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-writer-sealed.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-writer-state-error.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-writer-state-light.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-after-writer-write.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-before-envelope.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-before-front.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-before-phone-front.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-before-phone-mid.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/screens/margin-before-replay-10s.png
Binary file added docs/screens/margin-before-replay-end.png
Binary file added docs/screens/margin-before-replay-mid.png
Loading
Loading