Repository navigation
0.22.0
Seven features: three new pens, optional cloud sync with Google Drive or OneDrive, two-way page references, colours with meaning, instant axes, custom covers and an automatic lecture header. The notebook format moves to version 20 (the new pen tools and the nib angle): the migration from version 19 is automatic, and 0.21 and older open a v20 notebook read-only and never overwrite it. Cloud sync is off by default and uses your own OAuth client; the plugin ships no client ID or secret.
How the new features work together
- The cloud sync is joined to the Google Drive and OneDrive sign-in at load; Google's client secret lives under one device-local key and never in the token blob,
data.jsonor the vault. The new pens: ghost guide lines and scribble to erase work with the fountain pen and the brush (not the marker), the colour-meaning filter dims the marker too, and an L or a cross drawn with the marker is not turned into axes. Floating pills that share a corner (slide-back, symbols strip, "Referenced on", colour-filter pill, lecture-header chip, a parked minimap) are stacked instead of overlapping. The pen options popover leaves a strip of page below it on a phone held sideways, so a tap on the page still closes it.
New pens and document format 20 (#35)
- New pens (#35): fountain pen, brush and marker. The pen options have a Pen type row. The fountain pen is a nib: lines drawn along the nib angle are thin, lines across it thick (pressure still modulates the width, ends are crisp, nothing tapers). The brush answers to pressure (fine tip to full belly) and speed (thinner when it is fast), grows from a point and closes to a point. The marker is a flat chisel: constant for any pressure, a little narrower along the nib, 85% opaque and painted in stroke order (above the ink written before it, with that ink showing through), not multiplied like the highlighter. The fountain pen and the marker have a Nib angle (a slider with a little bar that leans like the nib); the angle is stored on the stroke. The same look in the canvas, the wet ink, thumbnails, SVG, PDF, PNG and the interactive HTML export; eraser, lasso and moves work on their outlines, and a rotated selection turns the nib with it. A hold-still shape made with a new pen becomes an ordinary shape.
- Favourites, pen sets and the style eyedropper remember the kind (and the nib angle). Settings > Writing has Pen type (the pen the pen tool starts with) and Nib angle.
- Document format v20. The tools
fountain,brushandmarker(alwaysrender2) and the optional stroke fieldnib(whole degrees 0 to 179, absent = 45, only the fountain pen and the marker have one). The v19 to v20 migration refuses a v19 file that already has a new tool (no version wrote one) and drops a straynibkey; read leniently, an unknown tool name is a pen (counted) and a bad nib is dropped (counted). 0.21 and older open a v20 file read-only.docs/schema/notebook-v20.schema.jsonreplaces the v19 schema; the geometry of the pen, highlighter and shape is frozen by golden tests (tests/pens-golden.test.ts).
Cloud sync with Google Drive and OneDrive (#126)
-
Cloud sync with Google Drive or OneDrive (#126), the engine and the settings. Off by default and opt-in per device, no telemetry. Settings > Sync & safety has a Cloud sync group: the service, your own OAuth Client ID (the same on every device; Google's Client secret stays in this device's local storage, never in
data.json), the account (Sign in, Change folder, Disconnect), Sync now with the last result (Stop while running, Review when a run waits for a decision), what to sync (whole vault, selected folders, or include / exclude globs and file types), sync on open, on close, every N minutes, Wi-Fi only (where the network type is unknown, a phone or tablet holds the automatic runs and a desktop runs), a large-file rule (ask or skip above a size) and the activity log of the last 50 events. Command Cloud sync now; a status bar item on desktop..obsidian,.trash, temporary files and the backup folder (#127) are never synced. -
Safety rules. Three-way sync against a per-device state in the plugin folder (
cloud-sync/state-<device>.json, remote index and base with SHA-256): the first sync is a union and deletes nothing; a deletion is propagated only from a synced, unchanged state and always to the trash (Obsidian's on this side, the cloud's on the other); more than 20 deletions (or 3 and over 30 % of the tracked files) stop the run and ask (Keep them copies them back, Delete them goes ahead); a file changed on both sides keeps both, the cloud's asName (conflict YYYY-MM-DD HH.MM Device).ext, which the #122 merge offer recognises; uploads are conditional on the cloud revision and the run re-plans when the cloud changed meanwhile; open notebooks are saved before upload and never replaced while they hold unsaved ink; downloads go through the usual external-change reload. A damaged state file is kept as.bad.jsonand the next run lists everything again without deleting. Transient errors retry with back-off (honouring retry-after); a sign-in problem stops and asks to sign in again; a missing cloud folder is an error, never "everything was deleted". No document format change. -
Code. Pure, Node-tested logic in
src/sync/(rules.ts,state.ts,planner.ts,conflict-name.ts,engine.ts,settings.ts,network.ts,sync-memory.ts); Obsidian wiring insrc/sync/sync-service.tsandsrc/sync/vault-adapter.ts; the sign-in contract insrc/sync/auth-ui.ts, implemented over the providers bysrc/sync/auth-adapter.ts(wired insrc/sync/auth/obsidian-auth.tsand plugged in at load withcloudSync.setAuth; Google's client secret has ONE device-local key and is kept out of the token blob, the client ID is the only OAuth value in the synced settings, and the Account row says that every device must use the same client ID because Google'sdrive.filescope only shows the “Notebook sync” folder this client created); UI insrc/view/cloud-sync-settings.tsandsrc/view/cloud-sync-modals.ts. Tests:tests/sync-planner.test.ts,tests/sync-rules.test.ts,tests/sync-state.test.ts,tests/sync-engine.test.ts; harnessdoc=synccore. -
Cloud connector: Google Drive and OneDrive providers and sign-in (#126, part 2). Sign-in with the OAuth 2.0 device code flow (RFC 8628), the same on Android and desktop: a dialog shows the code and the address, with Copy code, Open sign-in page, a countdown and Cancel, and handles denied, expired, refused-client and network failures with Try again. The plugin ships no client ID or secret: you register your own app (step-by-step guide in
docs/cloud-sync.md). Google usesdrive.file(the only Drive scope the device flow allows besides the hidden app folder), so everything lives in aNotebook syncfolder the plugin creates; OneDrive usesFiles.ReadWrite.AppFolder, so everything lives in the plugin's app folder (Apps/<app name>) and nothing else of the drive is visible. Tokens stay on the device (Obsidian's local storage), refresh by themselves, are never logged; Disconnect revokes them where the provider allows (Google). Both providers list changes incrementally (Drive changes feed, OneDrive delta) with paths rebuilt from parent ids, upload large files in chunks, refuse to overwrite a remote file that changed (If-Matchon OneDrive, a revision check just before the write on Drive), move removed files to the remote trash (never a permanent delete), and retry 429/5xx with backoff andRetry-After. HTTP only throughrequestUrl. No format change.src/sync/auth/,src/sync/providers/; teststests/sync-*.test.ts; harnessdoc=syncprov.
Colours with meaning (#101)
- Colours with meaning (#101). Settings > Reading & PDF > Colour meanings opens a legend editor: give each ink colour a name (red = definition, blue = example), reorder, recolour, add and remove; Add the usual meanings starts from red / blue / green. Colour matching (strict, normal, loose) says how close a stroke's colour must be to a legend colour; two legend colours that are too close are flagged. A notebook can have a legend of its own (its menu, Colour meanings…), kept in
_meta/meanings-<device>.json(one file per device, like the quick tabs; read leniently, unknown fields kept, an unreadable file is never overwritten). - Filter by meaning. The notebook menu has Filter by meaning…: choose a meaning and the ink of the others (and of no meaning) is drawn faint, with a pill at the bottom left to clear it. It is view-only (the renderer redraws its static layer once; nothing is saved and the document is not touched) and not kept when you switch notebook.
- Digest by colour. Digest by colour… writes
<Notebook> — Colours.mdnext to the notebook: one section per meaning in legend order, a picture of each place the colour was used (close ink of one meaning is one place), the PDF text under it and a link to the page. Only the part between thenotebook-meaningsmarkers is rewritten; your text around it stays, a second run makes no new pictures, an unpaired marker is left alone and a note of yours with that name is added to only after you agree. - No document format change. New:
src/model/colour-meaning.ts,src/library/meanings.ts,src/library/meanings-store.ts,src/view/colour-meaning.ts,src/view/meaning-modals.ts,src/view/meaning-digest.ts; the renderer has a view-onlysetInkDim.
Custom covers (#53)
- Custom covers (#53). Change cover… (library card menu and the notebook tab menu) opens one dialog with four sources: a generated Pattern (families, colour, new variation), an Image from the vault or the device, a Page of the notebook (stepper) and five designed Templates (Classic, Band, Frame, Minimal, Poster) that put the notebook name on generated art. Images and pages are moved and zoomed in the 3:4 frame (drag, wheel, pinch, slider, arrow keys). Nothing is written until Use this cover: the picture is baked small (540 x 720 JPEG), stored as a content-addressed asset in
_assetsand set as the existingmeta.coverArtimage cover, so there is no format change and no new sidecar. An open notebook takes it as one undo step; a closed one through the safe read-patch-write; a picture this action created is trashed again if the change fails. Large photos are reduced to 1600 px for editing (Android memory). Crop mathssrc/model/cover-crop.ts, templatessrc/model/cover-template.ts, paintingsrc/ui/cover-compose.ts, dialogsrc/library/cover-dialog.ts. Tests:tests/cover-crop.test.ts,tests/cover-template.test.ts.
Two-way page references (#179)
- Two-way page references (#179). A page that other pages of the notebook link to (a page link in a text box or a sticky note) shows a quiet chip, Referenced on p. 3, p. 12; tapping it lists those pages with a jump to each. Links name pages by id, so reordering pages keeps them; deleted pages, links to itself and links to other notebooks are ignored. The index is derived in small idle slices and cached, nothing is stored (format unchanged). The new setting Show pages that link here (Pages > Outline) turns it off. Tests:
tests/page-refs.test.ts; harnessdoc=pagerefs.
Instant axes (#206)
- Instant axes (#206). An L (up, then right) or a + of two crossing lines drawn with the pen is offered as Cartesian axes: a Make axes chip for nine seconds, or made by itself with the setting L or + drawn as axes (offer, make, leave as ink). The result is plain shape ink (one arrowed stroke per arm with evenly spaced ticks following the page grid or line spacing) and small number labels, all in one new group and one undo step that also takes away your lines. Ticks on axes and Numbers on axes settings. Axes in the insert sheet drops four-quadrant axes where the pen last wrote. No format change; the input pipeline is untouched (the gesture is read when a stroke ends, with the shape recogniser of hold-to-snap).
Automatic lecture header (#210)
- Automatic lecture header (#210). When a class of the timetable is on for the notebook, its header (course, lecturer, room, date and start time) can be written on the page you are writing on: two small text boxes in a fresh group (course larger, the rest in a quiet line under it) at the top margin, as one undo step. It goes only where the page is empty: it moves down to the first free spot in the top of the page and never overlaps ink or objects; with no free spot nothing is written and the chip Add lecture header waits. It is offered or done when a new page is added during the class, and when lecture mode starts on a page that is not a lecture page of its own. New settings in Study > Timetable: Lecture header (Off / Ask / Automatic; Ask shows a quiet chip) and which fields to write (Lecturer, Room, Date, Start time). New command Insert lecture header: uses the class in progress or else the closest class of today, and refuses a locked page. Date and time follow the interface language (English, Italian). No document format change. Pure rules in
src/timetable/lecture-header.ts, view side insrc/view/lecture-header.ts. Tests:tests/lecture-header.test.ts. Harness:dev/harness/lecthead-check.ts(doc=lecthead).
Review fixes
- Cloud sync waits for the vault to load (review W22 S1). No run starts (not even Sync now, which says why) until Obsidian's layout is ready and its metadata cache has indexed the vault (30 s fallback), so a file not listed yet is never taken for a deletion.
- Sync deletions here go to Obsidian's
.trash(S2), never through the Deleted files setting, which can be Permanently delete. - Google Drive: no lost or doubled writes (S3, S4). A version another device wrote just before ours is read from the file's history and kept as a conflicted copy; a trash that raced a write is undone. Files and folders are created with ids reserved by
files.generateIds, so a retried request cannot make a twin; two cloud files with one name are no longer skipped: every device follows the same one and the other is kept as a conflicted copy before going to Drive's trash. - Disconnect (S5) asks first, stops a run in progress and waits for it before forgetting the sign-in and the sync state; it can also forget Google's client secret. Signing in to the other service disconnects the current one first.
- OneDrive (S6, S13, S14). The scope is now
Files.ReadWrite.AppFolder: the plugin syncs with its app folder (Apps/<app name>) and sees nothing else of the drive. The revision is the file's content hash, so renames and other metadata changes no longer make conflicted copies. On older OneDrive for Business accounts that refuse the folder's change feed, the folder is listed file by file instead of reading the whole drive. - Safer automatic runs (S7, S16). Runs at start-up and when leaving the app never delete (the status counts the deletions that wait); automatic runs stop and ask above 10 deletions. On a phone or tablet, an unknown network type holds the automatic runs when Wi-Fi only is on, and the new Size cap on phones (default 50 MB) keeps larger files from being transferred there.
- Names (S9, S10). Names that cannot exist on every device are skipped on both sides with one notice and never deleted because of it; names that differ only by case or Unicode form are never both written, and a case-only rename is followed. A conflicted copy outside the sync scope stays local (S8). The state is saved at most every 10 seconds during a run (S11). Drive's upload session must be on Google's API host, and error texts no longer carry addresses (S15).
docs/cloud-sync.mdexplains that folders made on the Drive website are invisible to the plugin (S12). Newsrc/sync/names.ts; teststests/sync-review-w22.test.ts,tests/sync-service-w22.test.ts. - Kept files stay kept (review round 2). A file you chose to keep (Keep them) that cannot be copied back yet (above the size cap on phones, or waiting for the large-file rule) is no longer tracked as synced, so a later run sees it as new on one side and never moves it to the trash.
- Cloud sync, round 2. Two cloud files with one name: every device follows the newest one. A local rename to a name that cannot be synced is not taken for a deletion in the cloud. On Google Drive, a version written by another device at the same moment that cannot be checked or is above the size cap is reported in the activity log (it stays in the file's version history), a twin above the cap is skipped with a note instead of downloaded, and a replace finds its file when two folders share one name. A OneDrive listing whose next page leaves Microsoft Graph, or that does not finish, fails the run instead of returning part of the folder.
- Lecture header and deleted pages. The pages of a notebook count as seen from the moment it opens, so a first change that deletes a page no longer makes the remaining pages look new.
- Lecture header and undo. In Automatic a page only counts as new when it was created by a forward edit: a page that comes back through Undo or Redo never gets a header, so the redo stack stays intact.
- Unknown tool names. A stroke whose tool this version does not know is still read as a pen and counted (with the usual backup); the strict write still refuses such a name. Documented in
docs/format.md. - Style eyedropper. Taking a ballpoint or shape stroke selects the ballpoint (and the default nib), so it no longer keeps writing with the fountain pen.
- Marker memory. The marker's wet canvas is created when a marker stroke starts and released a few seconds after the last one; other pens never touch it.
- Colour meaning and the marker. The "filter by meaning" dimming applies to marker ink like every other ink.
- Axes in Automatic. The short wait before an L becomes axes is dropped by the next pen contact, a scroll or zoom by you, or a page change, and never runs while the pen is on the screen.
- Digest by colour. The write reads the note again: if its markers vanished while the pictures were rendered, you are asked before the section is added to your note.
- Colour meanings sidecar. Unknown fields inside a legend entry, and entries this version cannot read, are written back unchanged until you edit that legend.
- Cover picture. Two "Use this cover" run one after the other, and a failed one never trashes a picture that another notebook or an open one already uses; the dialog's first read no longer leaves an unhandled error.
- Floating pills. On a phone the strip, the "Back to current page" pill and the "Referenced on" chip start below the "Lecture mode" chip; the minimap parked at a bottom corner, the colour-filter pill and the lecture-header chip stand above the contextual bar; the pill and the chip start to the right of a minimap at the bottom left. The new harness scenario
pillstackputs all of them on screen at once.