Tippani টিপ্পনী

All local — no email round-trips anywhere in this section, which is the constraint that decides most of its shape.

• Sign in through the reverse proxy you already run — OIDC, and the cheaper half first, forward-auth: trust a configured identity header when TRUSTED_PROXY is set, which is the same trust boundary the login rate limiter already reasons about for X-Forwarded-For. Anyone fronting their box with Authelia, Authentik or Tinyauth wants their whole estate behind one sign-in, and it is the most-asked thing on this list. Local passwords stay, and stay the default.
• Stronger sign-in (opt-in) — passkeys (WebAuthn) and TOTP 2FA layered over today's password + hashed-token sessions, for boxes reachable past the LAN. Off unless you turn it on; the password stays the fallback.
• Scope the API tokens, and add webhooks. Device tokens exist; what they have no notion of is scope — a token that may read stats but not write quotes, which is what an Obsidian sync or the dashboard widget actually wants. Outbound webhooks on events are the other half.
• List and revoke browser sessions individually. Paired devices can each be unpaired by name, but browser sessions can only be dropped all at once by changing your password — so "sign out that other laptop" currently means signing out everything.

Tippani installs as a PWA and then behaves like a browser tab with a nicer frame, because there is no service worker at all. That is the real reason it doesn't feel native — more than any missing gesture — and it is the first thing here.

Cache the shell and recently-viewed data, queue writes while offline, flush on reconnect. A queue flush is a burst of concurrent writes, so it needs a retry path that distinguishes "the box is busy" from "the box refused", and the write path underneath it now behaves well enough to write one against.

Gesture ground rules

Today the only gestures are scrolling, the drawer's swipe-to-close, and dragging a control thumb or a sticker. Adding more is worthwhile, but a web app that fights the operating system for a swipe loses, so the constraints come first and apply to every gesture below.

• Nothing starts at a screen edge. Ignore any gesture whose first touch lands within ~32 px of the left or right edge — that belongs to the iOS back-swipe and the Android back-gesture — or in the bottom home-indicator strip. No code measures this today, so it gets written rather than reused.
• Prove direction before capturing — 10 px on the dominant axis, dominant by about 1.5× — so a gesture can never steal a scroll.
• touch-action: manipulation on card chrome to drop the double-tap-zoom delay; touch-action: none only on the element that owns a gesture, never on a scrolling ancestor.
• Every gesture is additive. The ⋯ overflow, the ♥ button and the filter sheet all stay exactly as they are. That is both the accessibility requirement and the answer to how anyone discovers a gesture in the first place.
• One Settings toggle turns card gestures off wholesale. prefers-reduced-motion is already honoured; the toggle is not.
• navigator.vibrate(10) on commit — Android only, iOS Safari has nothing — which is most of what makes a gesture feel deliberate rather than accidental.

The set, in build order

1. Double-tap a quote card to toggle ♥. Understood everywhere, and it gets the same heart-bloom the button does.
2. Pull down at the top of a list to refresh. Standalone display mode suppresses the browser's own pull-to-refresh, so this is mine to implement, with progressive feedback and overscroll-behavior-y: contain.
3. Long-press a card away from its text for the ⋯ menu as a sheet — today it selects the card, or anchors a menu.
4. Swipe up or down on a review card for got it / forgot. The best fit in the whole list: vertical, so it cannot collide with either platform's back gesture — the Anki-mobile pattern rotated onto the safe axis — and a review card isn't a scroll container, so there is nothing to conflict with. A tap still reveals, and the buttons stay.
5. Swipe down to dismiss a bottom sheet. MobileSheet already exists, the gesture lives entirely inside it, and every native sheet works this way.
6. Pinch the Library or Catalogue grid for cover size and density — the direct-manipulation form of the Settings sliders that already exist, snapping to the same discrete sizes.
7. Pinch and double-tap inside the cover Lightbox to zoom and pan. The one place native zoom semantics are the right answer, so implement them rather than suppressing them.
8. Double-tap the top bar to scroll to top, riding the scroll memory that is already there.
9. Long-press ＋ Add for a quick-action sheet, so the same actions the installed app icon already offers on a long-press are reachable from inside the app.
10. Two-finger tap to undo — genuinely unclaimed on both platforms, and it pairs with the delete-undo toast that already exists.
11. Long-press a colour swatch to make it the default for new captures.
12. Drag to reorder anthology entries and staged-import groupings; the sticker drag already proves the primitive.

Two more are unblocked now that trash & undo (§1) has landed and a mis-swipe is recoverable: horizontal swipe inside a card's own bounds for share/edit/delete, Gmail-style, rubber-banding back below threshold and never deleting on the swipe alone; and horizontal swipe on a work-detail hero for previous/next work in the current filtered order, which is the riskiest of the set for being screen-width and horizontal, so it stays on the hero and never the whole page.

One is rejected outright, recorded so I don't revisit it: swiping between the four bottom-nav tabs. It is a screen-width horizontal gesture that fights the back gesture at both edges and any horizontally scrollable content in between, and the bottom bar is already one tap away.

Discoverability rides the existing spotlight: a short gesture chapter in the tour. The help panel already draws the two gestures that exist — the long press and the drawer's leftward swipe — so a gesture added here arrives with a clip waiting for it.

Low-cost ways to get text in without a file:

• PWA share-target — Tippani already installs as a PWA, so register it as a share target: "Share → Tippani" from any app (a reading app, a browser, your phone's own text selection or its built-in OCR) drops straight into quick capture. This is also how a photographed page gets in — the phone recognises the text, you share it.
• Bookmarklet — one click that POSTs the current page's raw HTML to Tippani, parsed server-side by reusing the existing Hardcover / Goodreads / IMDb HTML importers. Deliberately minimal: just the page, no Bookcision-style JSON layer to install or keep working.
• Paste a pile — one textarea, blank-line separated, becomes N staged quotes on one work. The "just let me dump what I typed in Notes" path that every parser-based importer misses.

A named, ordered list of quotes drawn from anywhere in the library, carrying prose of its own: an introduction, and my commentary between the entries. It is not a tag with a nicer hat — the two things a tag cannot do are hold an order and hold your writing, and those are the whole point.

This is the missing output of a commonplace book. Everything in Tippani today points inward: you file a passage, you find it again, you get asked about it. An anthology is what you make from the collection — a sequence you arranged, on a theme you chose, with the connective tissue that explains why these twelve passages belong next to each other. Letterboxd's lists are the closest proven form; the nearest thing in the annotation world is Zotero's extract-annotations-into-a-note, which is the most-used feature it has.

Most of this shipped. The API landed in 2.0.0, the screen in 2.1.0, and 2.1.2 added the themed round and per-anthology field visibility — six switches deciding what each passage shows, governing the reading view and the Markdown alike, so a collection of film lines can name its actors and a book of proverbs can carry nothing but the words. Composing works from any selection, the per-entry commentary is there, and the Markdown export round-trips.

And the rest shipped by 3.0.0 (#18, closed): EPUB export, a small book of your own quotes, built with the standard library's archive/zip. What comes next is its own card below, Anthologies you can arrange and print.

The registry, web/frontend/src/help.jsx, keys the help copy by screen; the words live in the locale files. The tour and most info dots resolve out of that same file under namespaces of their own, and the glossary is hand-written English — so the same control is still described more than once. Making it a single source is what is left, and it only gets more expensive.

The panel's own shape shipped in 2.0.1 and is not what remains here: an entry is now one front-loaded sentence with the rest folded behind a more, capped by a test, with a rail of screen sections, live swatches and drawn gestures. That work made this section cheaper rather than smaller — an info dot needs one short sentence, and there is now one short sentence to read.

• The info dots should read from it. The panel does; the dots still carry their copy inline, which is precisely the drift this section exists to end.
• The glossary should be generated from it — glossary-css.mjs already feeds it the built CSS and gates that in CI. The copy is the half still written by hand, and the likeliest to go quietly stale.
• The tour should read it too. Step copy and panel copy overlap today and neither knows about the other; the same change has already had to be made twice by hand, which is the argument.
• Deep links — /library?help=filters. Not "add a key": the shell parses a pathname and pushes a path, with no URLSearchParams anywhere, so whoever builds this builds the app's first query-string state.
• The completeness test. Tests already pin every screen to an entry and every entry to copy; the third clause — every dot resolves to a key — is unwritten, and the 33 English literals still sitting in eight files are why.

Most of this has shipped. The contrast work is done in both halves: ink and hairline contrast raised to WCAG AA across all four looks, and a switch in Settings for a reader who cannot or will not set it at the operating-system level — resolving to the same state as prefers-contrast: more rather than competing with it. The quote text gained the two axes that were fixed, line height and measure, beside the size dial that was already there; line length is the largest readability lever there is in a body of prose, and the paper and film looks are deliberately generous with it — right for reading a card, and exactly what somebody with low vision needs to be able to narrow. And the quote box no longer offers only serifs: OpenDyslexic is bundled and named in Settings → Type, for the quote text and for the interface both.

• A named, focusable equivalent for every gesture added in §2. The rule is settled, and each of the four gestures listed under §2’s ground rules now satisfies it: scrolling is the platform’s own and answers a keyboard already, the drawer closes from a button as well as a swipe, a control thumb is a real <input type="range"> and answers the arrow keys, and the seal on a quote — the last thing here that could only be dragged, and a position kept with the quote rather than a flourish — answers them now too. What is left is holding each gesture §2 adds to the same rule as it lands.

The after-import jobs the bulk editor and staging miss.

• A shared text-cleanup pass — de-hyphenate across line breaks, drop page numbers and running heads, normalise the quote marks and ligatures that get mangled in transit. §20 lists all of this as OCR post-processing, but it belongs server-side and shared, because the free-text sources and OCR both produce it, and the dedupe hash's typographic fold is a map worth borrowing.
• Per-batch import rollback. Approval deletes the staged rows and the import_batches row too, and nothing it writes carries a batch id — so this needs a provenance record, not just an endpoint.

Kobo (KoboReader.sqlite), Apple Books, a Readwise export, and read-later apps (Instapaper · Pocket · Matter), all folded into the same idempotent, cross-source dedupe. Kobo is unwritten rather than unverified: no parser exists yet, and I have no device here to test one against. The Kindle My Clippings.txt parser already reads eight locales by structure rather than by English, so it needs the same thing — real files from those Kindles.

Three more, added after a look at what the neighbours read:

• KOReader annotations (.sdr/metadata.*.lua). To be clear about which half of KOReader this is: Tippani reads the annotations, not the books. Grimmory, Kavita and Calibre-Web all sync KOReader progress, which means the e-ink crowd is already the overlapping audience — and they are the people who highlight most.
• A generic CSV / JSON importer with column mapping — pick the file, map its columns onto quote fields, preview, stage. This is the future-proof answer to every source there will never be a bespoke parser for, and staging is what makes it safe enough to offer.
• Subtitle files (.srt / .vtt) — drop one, pick the lines worth keeping, and they stage as dialogues with the timestamps already correct. The film-side equivalent of a Kindle export, and the one thing the movie-quote sites prove people actually want to do.

Today a lookup fans out to whatever happens to be configured, in an order baked into the code, and you find out what it consulted by reading the result. I want the sources to be mine to pick — per lookup, and as a saved default.

• A source picker on every metadata fetch. Checkboxes for the sources that apply to what is being looked up, remembered per kind: books on Google Books, Open Library and Amazon, films and shows on TMDB and TheTVDB, games on IGDB and Wikidata, people on Open Library and TMDB. "Just Open Library" is also the honest answer to a source wrong about a particular book.
• A source with no key should read as inactive where you are asking. Settings already says the state out loud — a chip for whether film lookups have a key at all, another for whether the last book lookup worked. What is still open is the same truth in the lookup: a source that cannot answer should be greyed out in the picker, with a link to the card that takes a key, rather than dropped silently from the fan-out.
• It matters most for people. Looking up Subhas Chandra Bose should query Wikidata rather than the film database a speaker is sent to today — which means writing a Wikidata person client, not ticking a box over one that exists. An actor already goes to TMDB alone.
• Pairs with the re-verify flow that already exists: once you can choose sources, "re-check this show against TheTVDB only" becomes a sensible thing to ask for.

Extend tagging to books — tags live on every quote kind but on no work — then a view that groups them by tag, which Search previews for quotes today. Curated, named groupings ("Best of 2026", "to reread") as first-class collections: a third way to group these rows, after boards and anthologies.

A note on the word: this section used to be called Collections & shelves, but "shelf" now means where you stand with a work — reading, paused, completed — so what this section builds is tag shelves, and the plain word belongs to the other feature.

Tag hygiene belongs here too, because the vocabulary is load-bearing already:

• Merge tags, which every managed vocabulary needs by its second year. The usage counts skip utterance_tags, so a tag worn only by standalone quotes reads zero uses — fix that first, then re-point three join tables.
• Nested tags — theme/grief, displayed hierarchically. Deliberately a display convention over the existing name column rather than a parent id, so there is no schema change and no migration to regret.
• An optional mood and pace starter vocabulary. The thing StoryGraph is loved for is, underneath, a well-chosen tag set; offering one as a suggestion on the Tags page costs a list of strings and no new field.

Unglamorous, low-risk, and the sort of thing that turns up as an issue rather than a feature request.

• Book fields — format (paper · ebook · audio), language, publisher, subtitle. Format and language are the two that get filtered on. Page count is deliberately not on this list: it is already stored as the progress bar's denominator, and a second metadata-sourced page count would give the app two numbers that can disagree. If it is ever wanted as canonical metadata it should feed that one, not sit beside it.
• Film and show fields — runtime, original title, country, language, certification. Four ride along in the TMDB responses already fetched; certification needs one more appendix. They are what a country or language breakdown needs.
• A per-season episode map from TMDB or TheTVDB. The shelf stores a season total and the current season's episode count, because that is what a viewer knows off the top of their head; a real map means progress through a long run stops needing you to supply each season's length by hand.
• "Attributed to" on a quote — for a book quoting someone else. An epigraph is currently credited to the book's author, silently, which quietly corrupts both the author breakdown and the author multiple-choice distractors.
• A locator-kind hint per book: whether its locators are print pages, Kindle locations or percentages. The staging location formulae already show that people care about locator arithmetic.
• A spoiler flag, blurred until tapped. Standard wherever reviews are public, and it matters as soon as anything is shared.

The shortcut registry shipped, legends on the buttons and all. What is left of the desktop gap is the layout itself.

• An optional denser layout — one toggle, not a redesign. The paper and film aesthetics are rightly generous for reading and expensive for triage.

• Ambient mode — full screen, one quote at a time, slowly cycling, in whichever skin is current. The paper and film aesthetics are the nicest thing about the app and are currently only ever seen at card size. This is also the version that earns its keep on a display wired to the NAS.
• Year in review — the numbers are already computed for the Stats page; what is missing is the sequence that walks you through them and the single image worth sharing at the end. Drawn from quotes, tags, people and the review loop only — deliberately not from the read log, even though "books finished this year" is now sitting right there. See the note under Considered and set aside; this is the first place anyone would reach for it.

Shuffle and on this day were the cheap half of this section and shipped in 1.16.0.

A deliberately restrained take. Achievements mostly mark distance travelled — reading and collection milestones drawn from data already in the library and computed at query time: no counters table, no background jobs, no cron, nothing ticking. Off by default, private, nothing social and nothing that phones home; shown as a modest, dismissible shelf on Home or Profile. Candidate milestones, all derivable from what is already stored: your first hundred highlights; a whole book carried through the forgetting curve; ten authors on the shelf; a passage recalled correctly five times; a series completed; a film quoted from every act.

The one place a streak earns its keep is the spaced-repetition review, and one already counts the days you cleared the due deck, on Home and in the drawer. What this section changes is the miss: the count drops to zero, where it should spend a built-in grace instead and never be dressed up as a loss. "You broke your streak!" banners are exactly what I won't do. Streaks stop at the review; nothing else in the app grows one.

It waits on appetite alone now: the review loop its one streak rides on has landed, and being off by default makes it easy to wait for.

The way a self-hosted app wins "works with everything" is not by writing thirty integrations; it is by speaking two or three formats other tools already read.

• A feed of recent highlights — RSS, Atom or JSON, token-scoped, riding the scoped tokens of §1. One endpoint reaches Obsidian, FreshRSS, Home Assistant, e-ink dashboards and a terminal widget, which is a better return than any single bespoke integration.
• A random-quote endpoint in SVG — the JSON form is GET /shuffle, which a device token reaches. SVG rather than PNG: its text is string concatenation, and the dashboards that would display it render SVG natively.
• CSV and JSON export. Markdown and the zip serve Obsidian well; CSV is what a spreadsheet needs and JSON is what a script needs, and both are small next to the export builders already written.
• EPUB export of your own highlights — a small readable book of your own quotes, to put back on the e-reader they came off. archive/zip is already imported for the library export, and an EPUB is a zip with three XML files. Nothing else in this category does it.
• A print stylesheet, for the paper version of the same idea.
• BibTeX / CSL-JSON per work — nearly free, since ISBN, author and year are already stored, and the one thing an academic user asks for first.
• tippani quote and tippani export as CLI subcommands, alongside the existing serve / user / healthcheck. A fortune for your own library.
• Export presets — a named, saved combination of fields, template and filter, so the monthly dump into Obsidian is one command rather than six choices.
• More quote-image templates. quoteImage.js renders one layout in four skins; centred-serif, film-still, index-card and minimal, plus story, square and wide aspect presets. The one part of sharing an export cannot do, since a picture is not a file format anyone else reads.
  The one worth building first is a portrait layout: the author's, actor's or speaker's photo bled down the left and faded into the quote text on the right — the shape that actually reads on Instagram and Facebook, where a centred serif card does not. The portraits are already fetched, disambiguated and stored locally, so the art is on disk and nothing new needs downloading; the work is the gradient mask, a legible text well over it, and a sensible fallback when a person has no photo. Square and story crops matter most here, since that is where it would be posted.

A widget for Homepage (and similar self-hosted dashboards), so Tippani shows up as a live tile on your NAS dashboard. GET /stats already answers a device token with the totals and the latest quiz score, unscoped and far from small; today's pending spaced-repetition count only the review loop knows. Opt-in; nothing exposed without a token.

Tier 2 and most of tier 1 shipped in 3.0.0 (#25, closed): Profile → Dashboard widget makes a read-only key, GET /api/widget answers four numbers (works, quotes, forgotten, mastered) for that reader's own library, and the README has the services.yaml to paste. Tier 1 landed as that README section rather than a docs page, and without the optional homepage.* compose labels. What is left is those labels and tier 3.

The three tiers, as planned:

1. Document what already works — Tippani's unauthenticated /healthz means any dashboard can ping it today, so a "Dashboards" docs page with a ready-to-paste services.yaml snippet and the optional homepage.* compose labels costs nothing and lands first.
2. Custom-API widget — Homepage's customapi widget can render live counts with zero upstream code, but its requests come from the Homepage server with no session cookie, so this tier rides on the scoped API tokens of §1: a slim read-only stats surface accepting Authorization: Bearer, plus a documented field mapping. This is the real deliverable.
3. Native first-party widget (later) — a PR into gethomepage/homepage. Gated upstream: the widget must target a feature-request discussion with ≥20 up-votes, and widgets for projects under about a year old get declined — so the discussion gets opened early to accumulate votes, and the PR waits for 2027. It consumes the exact endpoint tier 2 already built.

• A /metrics endpoint (Prometheus), behind a token and off by default. This audience runs Grafana, and the numbers are already computed for Stats.
• Off-box backup without a scheduler. Uploading to rclone, WebDAV or S3 on a schedule means a timer in the app and a dependency, both of which are refused elsewhere in this document for good reasons. The version that fits is to ship the primitive — a documented one-line curl against the existing backup endpoint, plus a tippani backup --out subcommand — and let the box's own cron do the scheduling it is already running. The archive is encrypted before it leaves the process, so a copy sitting in someone else's bucket is not a copy of your library.
• A tippani open-backup subcommand. The archive is sealed (AES-256-GCM, Argon2id off the password you typed, or a passphrase you set), which is right for a file that holds every password hash on the instance and wrong for the moment you want to look inside one without restoring it. A subcommand that takes the credential and writes the plain .tar.gz to stdout keeps that door open without keeping the archive open — and it belongs to the binary rather than the API, because it needs no server running. Until it exists the format is documented in internal/httpapi/backup_crypto.go, in enough detail to write the fifty lines yourself.
• A keypair per user, so revoking an admin revokes their access to the archives. Today an archive carries its key wrapped under the instance recovery key, so any password on the box opens any archive the box made — which is right, and got there by being simple rather than by design. A keypair per user would let a backup add a wrap for every admin, including ones whose password it has never seen, and let revoking an admin drop just their wrap. That is the shape to reach for if the recovery key ever needs to be per-user again; it is deliberately not the shape now, because the published contract for this format is "fifty lines you could write yourself".
• An operator-held recovery code. Forgetting your password still loses the archives you carried off the box — the recovery key covers the box, and the password covers the file, and there is nothing behind either. A code printed once at first backup, wrapping the archive key a third time, would cover it. It means one more secret for an operator to lose, a print-once flow, and a CLI enrol command, which is a release rather than a paragraph.
• A read-only mode flag. The Pages demo already simulates one client-side; a server flag would let someone share a live instance without risk.
• A per-user storage cap, for anyone hosting for family. Images are the only unbounded growth path in the data directory.

Getting Tippani discoverable where self-hosters actually browse. No code here — outreach and asset prep, in dependency order:

• Icon CDNs first, since dashboards and directories pull art from them:
  • dashboardicons.com — open submissions via the site's form or a GitHub issue. Needs a clean tippani.svg in kebab-case; they generate the raster sizes. The mark uses an feTurbulence edge-roughen filter that some raster pipelines drop, so a flattened submission variant gets prepared first — flattening displaced geometry, not a noise layer.
  • selfh.st/icons — no external PRs accepted; icons are requested via GitHub Discussions and added by the maintainers. This is also where the selfh.st/apps directory sources its art, so it goes in before or alongside the listing request.
• selfh.st/apps — a one-person curated directory with no submission repo: reach out by email with the repo, a one-liner, a demo link and the icon. Being picked up by the This Week in Self-Hosted newsletter's "New Software" section is the usual front door.
• awesome-selfhosted — the biggest list, syndicated by many others, but it rejects projects younger than 4 months, counted from the first release (2026-07-03), so this waits until November 2026.

A pull source for anyone already running Grimmory self-hosted: point Tippani at that instance's MariaDB database and sync straight from its tables, with no export file in the loop. It reads book covers, edition metadata and annotations directly from Grimmory's schema and folds them into the same idempotent, cross-source dedupe as the file importers, so a re-sync never doubles a passage. Covers come across too, which needs read access to Grimmory's cover store — so the plan assumes both services sit in the same compose file: Tippani is handed the Grimmory DSN plus the relevant media path, wired through the environment. Read-only and opt-in — nothing runs without a configured DSN. A first pass is a one-shot pull, with a scheduled re-sync as the follow-up. Unverified until I can test it against a real Grimmory box.

A native Android client, Flutter so the source stays portable, in mobile/. Not a wrapper around the PWA: the point is the one thing a web page on a phone cannot do well, which is photograph a page of a physical book and turn it into a highlight. Recognition runs on the device (ML Kit), so the server gains no dependency, no CPU cost and no upload path — the reason server-side OCR was set aside doesn't apply to it.

The work that isn't the OCR call itself — which is thirty lines — is what makes it worth having: reflowing recognised lines into paragraphs from their bounding boxes, de-hyphenating across line breaks, dropping running heads and page numbers, normalising the quote marks and ligatures OCR mangles, and then a correction screen with the photo beside the text. A local mirror keeps browsing and the Daily Quiz working with no server, and captures queue offline and flush when the box is reachable.

Two notes on where the work belongs. The text cleanup above should live server-side and shared rather than in the app, because every import source produces some of it; that is §7. And the photo the correction screen already holds beside the text is worth keeping, attached to the quote: one nullable path column on an image pipeline that already stores covers, posters, portraits and stickers, and it keeps the evidence next to the transcription for the next time you doubt a line.

The server half of this is done — device tokens and pairing, list paging, gzip, the capabilities handshake (a revision behind anthologies and locales), noted_at on create so a queued capture keeps its real date, and duplicate 409s that make a retried flush idempotent. What remains is the app, and it is the largest single item on this page.

Android only. Flutter compiles for iOS and the Dart here stays platform-agnostic, but building and signing for iOS needs a Mac, and I don't have one — so no ios/ directory ships rather than an unbuildable one rotting in the tree. A fork with a Mac adds it with flutter create --platforms=ios . and a signing config; the README says Android and does not imply otherwise.