notes

7.0 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, 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. | `jsoncheck.hl` | JSON syntax pre-check (copy from tickets; hybriel#6) |
46. | `styles.hl` | all CSS (mobile first; accent = yellow); `shared/tokens.hl` = copy of worldapi-tokens |
47. | `shared/md-editor.js` | vendored copy of worldapi-components `md-editor.js` (served at `/md-editor.js`) |
48. | `login.js` | ident selector ↔ shell bridge |
49. | `tests/browser.mjs` | the gate (own server, own ident copy, real Chrome); `deploy.sh` runs it |
51. Data: `storage/mpackdb/{users,notes}.db` (never sent by deploy.sh). Only ever open COPIES of live data.
53. ## The sync API (`project.hl`; JSON, the session cookie is the login; 401 signed out, 400 for bad JSON/fields)
54. - `GET /api/me` → `{ user }` · `GET /api/notes` → `{ notes: [{ id, edited, gone }] }` · `GET /api/notes?id=` → `{ id, text, edited, created }`
55. - `POST /api/notes` `{ op:'save', id, local, text, base, at }` → `{ id, edited, text, copy? }` ·
56. `{ op:'delete', id, base }` → `{ ok }` | `{ kept, id, edited, text }`. `base` = the `edited` the device last saw, `at` = when it edited.
58. ## Run and test
59. ```
60. NOTES_PORT=8710 NOTES_WATCH=0 ./bin/hybriel project.hl # dev; needs IDENT_API_KEY/SECRET for a login
61. node tests/browser.mjs # the gate: ports 8701 (ident), 8702 (app), Chrome 8703–8709
62. ./deploy.sh [--dry-run] # gate → rsync to Byrodin → restart → URL 200 (architect)
63. ```
64. Environment: `NOTES_PORT` (dev 8710, container 45007), `NOTES_STORAGE`, `NOTES_SESSIONS`, `NOTES_WATCH=0`,
65. `NOTES_PUBLIC_URL` (default https://notes.worldapi.org), `IDENT_URL`, `IDENT_EXCHANGE_URL`, `IDENT_API_KEY`,
66. `IDENT_API_SECRET` (`.env` beside `project.hl`, never read by workers).
68. ## First deploy (architect)
69. Container `notes.worldapi.org` on `127.0.0.1:45007` replaces the demo-notes at the same address: back the demo up,
70. stop it, point the vhost to 45007 (WebSocket Upgrade headers needed), register the app in ident with the origin
71. `https://notes.worldapi.org`, put the key and secret into `.env`.
73. ## Hybriel notes
74. - `bin/hybriel` + `plugins/` (core crypto data fetch fs http http1 mpackdb proc time web) are vendored = hybriel **master
75. e6720b1f** (2026-09-26, mission 037: #103/#104 client fixes, #105 `headers`, #106 `let` per loop pass, #94 files in emit;
76. earlier #83 hashed `/__hl/…?v=` URLs + immutable cache, #82 socket reconnect, #95–#97 offline/PWA from project.hl — NOT
77. used, notes keeps its own sw.js / notes-offline.js). Built from a read-only `git archive master` (`zig build
78. -Doptimize=ReleaseFast -Dtarget=x86_64-linux-gnu.2.39` in `native/`), sha256 `4316934e…8a2003`. No local patch:
79. re-vendor = copy binary + plugins, run the gate. Previous copy (13ef4f9b): `.scratch/pre-037/`.
80. - The notes area is plain JS on purpose: IndexedDB, a service worker and offline edits cannot go through hl:web's
81. faces (they need the socket; it never reopens, hybriel#82). The framework's link click and `popstate` would navigate
82. through the socket, so the area claims its own link clicks and uses `history.replaceState` (Back leaves the app).
83. - Gate needs a secure origin for the service worker: Chrome runs with `--unsafely-treat-insecure-origin-as-secure`.
84. - Server restart closed open tabs' sockets for good (hybriel#82) — fixed in the vendored master since 035 (reconnect); not
85. checked by the notes gate. The notes area still uses its own JS (candidate for hl:web offline, #95–#97).