notes

9.6 KB

1. # notes.worldapi.org
3. A notes app in Hybriel (hl:web). Log in with ident; the **sidebar** lists your notes by subject, last edited first;
4. a click opens the note on the right, edited with the Markdown editor `<md-editor>`; **New note** and **Delete note**.
5. The notes are also kept **in the browser (IndexedDB)**: they open and can be edited offline, and sync with the server
6. (and other devices) when the network is back. Concept: `CONCEPT.md`.
8. ## How it works
9. - **Subject** = the first non-empty line of the note without leading `#` (at most 80 characters); an empty note is
10. "Untitled note". No separate title field.
11. - **Order** = `edited` (ms), last first. Only a *changed* text moves a note to the top.
12. - **Pages**: `/` (the list; on a phone the list alone) and `/note/:id` (the note; on a phone it replaces the list,
13. "All notes" leads back; from 50rem wide both show side by side). Signed out: only "Log in with ident".
14. - **Offline + sync** (ticket notes#2): `notes-offline.js` fills the notes area from the browser's own copy (IndexedDB
15. `notes-<user>`), every change is written there first and sent to `/api/notes` about 0.6 s later (and every 10 s a
16. pull looks for other devices' changes; also on "online", on returning to the tab; other tabs follow through
17. BroadcastChannel). `sw.js` (service worker, network first) keeps the page and assets, so a reload works with no
18. network; the page carries no note data. A note made offline gets a local id (`l…`) and its server id at the first
19. push (the address follows). **Conflict** (changed here and elsewhere): the later edit wins, the other version is kept
20. as a copy note ("kept as a copy …" line at its end). A delete of a note changed elsewhere meanwhile is refused (the
21. changed note stays). Deleted notes stay on the server as tombstones (`gone`) so other devices learn of it. Log out
22. first sends what is unsent, then this browser deletes its copy of the notes.
23. - **Private**: every function in `notes.hl` takes the owner's user id and only reaches that user's notes; another
24. user's note id answers "does not exist"; saving/deleting it is refused. A note is at most 200 000 characters
25. (refused, never cut).
26. - **Login**: ident's button flow (`/login/callback` → `?ident_code=` → server-side exchange) plus the identity
27. selector, as in gitoria; the session cookie is `notessid`, idle time 14 days. The session carries the users `@id`
28. only; the ident identity id never leaves the server.
29. - **Short ids (ident#23, antcolony mission 039)**: `users.identity` holds what ident's exchange answers — since ident#23 the identity's
30. public 5-character short id (`a68sz`), before that the per-app id (32 hex); `users.hl isIdentId` accepts both (the old
31. `isHex` check refused short ids). The switch: one-off `tools/migrate-short-ids.hl` (old → short id, idempotent, never
32. `finish`), gate `node tests/short-id-switch.mjs` (ports 8720/8721, no browser), runbook
33. `antcolony-docs/docs/short-id-switch.md` (Byrodin: `/CONTAINERS/projects/antcolony/docs/short-id-switch.md` once synced).
35. ## Files
36. | file | what |
37. |---|---|
38. | `project.hl` | routes, login callback, audience, server |
39. | `users.hl` | `users` table (`@id`, `!identity`), the ident exchange |
40. | `notes.hl` | `notes` table (`@id`, index `owner`; `{ owner, text, created, edited, gone, local }`), sync push / delete / conflict rules |
41. | `components/main.hl` | the shell: header, login/logout, faces `notesLogin` / `notesLogOut` |
42. | `components/notes.hl` | the page (`/`, `/note/:id`): only `<note-book id="notesapp">` |
43. | `notes-offline.js` | the notes area: sidebar, editor, New / Delete, IndexedDB, sync (served at `/notes-offline.js`) |
44. | `sw.js` | service worker: keeps the page + assets for offline use |
45. | `icons/` | app icons: `icon.svg` (source), `icon-192/512.png`, `apple-touch-icon.png`, `favicon.svg`, `favicon.ico` |
46. | `jsoncheck.hl` | JSON syntax pre-check (copy from tickets; hybriel#6) |
47. | `styles.hl` | all CSS (mobile first; accent = yellow); `shared/tokens.hl` = copy of worldapi-tokens |
48. | `shared/md-editor.js` | vendored copy of worldapi-components `md-editor.js` (served at `/md-editor.js`) |
49. | `login.js` | ident selector ↔ shell bridge |
50. | `tests/browser.mjs` | the gate (own server, own ident copy, real Chrome); `deploy.sh` runs it |
52. Data: `storage/mpackdb/{users,notes}.db` (never sent by deploy.sh). Only ever open COPIES of live data.
54. ## PWA (installable app, antcolony mission 046)
55. - `project.hl` `appIcons` / `appTouchIcon` / `appFavicon` / `appThemeColor` (token `darker`, the header) / `appBackgroundColor`
56. (`dark`) → hl:web serves `/__hl/manifest.webmanifest` (name `notes`, start_url/scope `/`, standalone) and links it,
57. the apple-touch-icon and theme-color from every head. Each icon has its own `file` route in `project.hl`.
58. - **Offline is notes' own**, not hl:web's: no `offline = [...]` in `project.hl`, because hl:web would then register
59. `/__hl/sw.js` for scope `/` and replace `/sw.js` (or be replaced by it). `/sw.js` is registered by `notes-offline.js`
60. once signed in; it is the only worker (the gate checks that, and that `/__hl/sw.js` is 404). Moving to hl:web's
61. offline = ticket notes#4.
62. - **Icons** (`icons/`): `icon.svg` = source (512; a note page with a folded corner and a pencil, yellow on
63. rgb(25,30,35); everything inside the maskable safe circle r=204, so one image serves `any` and `maskable`);
64. `favicon.svg` = the same drawing cropped tight, thicker strokes. Render:
65. ```
66. rsvg-convert -w 192 -h 192 icons/icon.svg -o icons/icon-192.png
67. rsvg-convert -w 512 -h 512 icons/icon.svg -o icons/icon-512.png
68. rsvg-convert -w 180 -h 180 icons/icon.svg -o icons/apple-touch-icon.png
69. for s in 16 32 48; do rsvg-convert -w $s -h $s icons/favicon.svg -o /tmp/fav-$s.png; done
70. magick /tmp/fav-16.png /tmp/fav-32.png /tmp/fav-48.png icons/favicon.ico
71. ```
73. ## The sync API (`project.hl`; JSON, the session cookie is the login; 401 signed out, 400 for bad JSON/fields)
74. - `GET /api/me` → `{ user }` · `GET /api/notes` → `{ notes: [{ id, edited, gone }] }` · `GET /api/notes?id=` → `{ id, text, edited, created }`
75. - `POST /api/notes` `{ op:'save', id, local, text, base, at }` → `{ id, edited, text, copy? }` ·
76. `{ op:'delete', id, base }` → `{ ok }` | `{ kept, id, edited, text }`. `base` = the `edited` the device last saw, `at` = when it edited.
78. ## Run and test
79. ```
80. NOTES_PORT=8710 NOTES_WATCH=0 ./bin/hybriel project.hl # dev; needs IDENT_API_KEY/SECRET for a login
81. node tests/browser.mjs # the gate: ports 8701 (ident), 8702 (app), Chrome 8703–8709
82. # (other ports: NOTES_GATE_PORT / _IDENT_PORT / _CHROME=8722-8726)
83. # includes the PWA checks; screenshots in .scratch/gate-*.png
84. ./deploy.sh [--dry-run] # gate → backup → rsync to Byrodin → restart → URL 200 (architect)
85. ```
86. Environment: `NOTES_PORT` (dev 8710, container 45007), `NOTES_STORAGE`, `NOTES_SESSIONS`, `NOTES_WATCH=0`,
87. `NOTES_PUBLIC_URL` (default https://notes.worldapi.org), `IDENT_URL`, `IDENT_EXCHANGE_URL`, `IDENT_API_KEY`,
88. `IDENT_API_SECRET` (`.env` beside `project.hl`, never read by workers).
90. ## First deploy (architect)
91. Container `notes.worldapi.org` on `127.0.0.1:45007` replaces the demo-notes at the same address: back the demo up,
92. stop it, point the vhost to 45007 (WebSocket Upgrade headers needed), register the app in ident with the origin
93. `https://notes.worldapi.org`, put the key and secret into `.env`.
95. ## Hybriel notes
96. - `bin/hybriel` + `plugins/` (core crypto data fetch fs http http1 mpackdb proc time web) are vendored = hybriel **master
97. ff51cf46** (2026-10-01, antcolony mission 048: #113 mpackdb update() duplicate ids, #115/#116 lambda members on faces, #118 `for`
98. over a literal list, client-built SVG namespace, hl:markdown #111 — notes uses none of these directly; before: e6720b1f,
99. antcolony mission 037: #103/#104 client fixes, #105 `headers`, #106 `let` per loop pass, #94 files in emit;
100. earlier #83 hashed `/__hl/…?v=` URLs + immutable cache, #82 socket reconnect, #95–#97 offline/PWA from project.hl — the
101. manifest (`appIcons`) is used since antcolony mission 046, `offline` is NOT: notes keeps its own sw.js / notes-offline.js). Built from a read-only `git archive master` (`zig build
102. -Doptimize=ReleaseFast -Dtarget=x86_64-linux-gnu.2.39` in `native/`), sha256 `e70631f0…eff3471b`. No local patch:
103. re-vendor = copy binary + plugins, run the gate. Previous copy (e6720b1f): `.scratch/pre-048/`.
104. - The notes area is plain JS on purpose: IndexedDB, a service worker and offline edits cannot go through hl:web's
105. faces (they need the socket; it never reopens, hybriel#82). The framework's link click and `popstate` would navigate
106. through the socket, so the area claims its own link clicks and uses `history.replaceState` (Back leaves the app).
107. - Gate needs a secure origin for the service worker: Chrome runs with `--unsafely-treat-insecure-origin-as-secure`.
108. - Server restart closed open tabs' sockets for good (hybriel#82) — fixed in the vendored master since 035 (reconnect); not
109. checked by the notes gate. The notes area still uses its own JS (candidate for hl:web offline, #95–#97).
111. ## History and worker briefs
112. - `LOG.md` — append-only history, one dated line per step (moved here from the antcolony LOG on 2026-10-01).
113. - `missions/NNN-*.md` — worker briefs for this app; `reports/NNN-*.md` — their reports (same name). Numbered per
114. project since 2026-10-01 (antcolony#40); older text, code comments and commits use the old antcolony numbers →
115. map: `/media/STORAGE/projects/antcolony-docs/docs/mission-map.md` (Byrodin: `/CONTAINERS/projects/antcolony/docs/mission-map.md`).