Promises and evidence
What Inkline promises, and the checks that show each promise holds. Every check here runs on every pull request unless it says otherwise; CONTRIBUTING.md says how to run them.
Where the checks run
| Check | What it runs | Where |
|---|---|---|
verify (ubuntu-latest) | npm run check: ESLint with Obsidian's directory rules, Prettier, types, the unit tests, the build, and this site's build; and npm run check:pinned, that the pinned fixtures' list still holds every line it had in each release from 1.0.0 | GitHub Actions, Linux; required |
verify (windows-latest) | npm run check, the same as on Linux | GitHub Actions, Windows; required |
e2e | The end-to-end suite in real Obsidian: 1.13.4, the manifest's minimum, on the oldest installer that runs it, and the latest public release. Four jobs, e2e (1/4) to e2e (4/4), run a quarter of it each, side by side, each on both versions; e2e passes only when all four passed and their records show every spec file run once and passed on both versions | GitHub Actions, Linux, under Xvfb; required |
directory checks | Obsidian's own action, with the rules its community directory scans for: the manifest, README, licence, styles, a build, and the bundle | GitHub Actions, Linux; on every pull request, not required |
e2e in Docker | The same suite in the image npm run test:e2e:docker builds | Weekly and on request |
| Weekly CI | Every check above, so that a new Obsidian release is tested within a week | Mondays |
| Settings | The live labels and rulesets against their files, and every issue's labels | Weekly and on request |
| Pages | This site, deployed and read back page by page | After changes to main describing the newest public release, or on request after publication |
| Release | The commit's required CI, the release checks, and the release's own files installed in Obsidian, as a dry run on request and on pull requests that change the release steps | On request, and on those pull requests |
The end-to-end tests assert on state, positions, and pixels read back from Obsidian, never by comparing screenshots with reference images. Where what Obsidian shows on the screen is itself the subject and the DOM, a canvas or a saved file cannot give it, as with a symbol's colour through a CSS mask or text drawn beside it, a test measures the pixels of a screenshot of the elements concerned, with stated tolerances. Screenshots are also kept as artifacts for review.
The promises
A deciphering session works from beginning to end
- A synthetic inscription is pasted as a tracing picture, copied into three distinct editable symbols with Make ink and Next, reused in another note from the library, renamed with both notes' links following, opened from its usage list, and read back in light and dark themes (journey.e2e.ts). The guide's screenshots come from this fixture, with no private notes or game artwork.
Symbol files stay readable, and look the same
A symbol is a PNG with a version 1 record. Reopening and saving it in the same version preserves its drawing. From the first stable release, later versions must keep released files readable and looking the same, as Versions explains.
- Unit tests of the PNG codec, the record, and symbol files: png.test.ts, record.test.ts, and ink-file.test.ts, including chunks that are not well formed, damaged records, and files from later versions however large.
- Pinned golden files in test/fixtures/format, real saved symbols with one for each kind of stroke and one with text about its symbol, read on every change, and redrawn in Obsidian's own renderer against their stored pixels, within stated tolerances (format.e2e.ts). From the first stable release, existing fixtures stay unchanged and new cases get new files.
- Pinned stroke outlines in test/fixtures/outline, one for each path through the algorithm the format specifies, with turns on and either side of a tie, and the pieces of polygons and of cut strokes: a change that would change how saved strokes look fails outline.test.ts.
- Every limit of the format is tested at the limit and just past it, with its number written out rather than taken from the code, so that a limit cannot move without failing a test (limits.test.ts).
- Every file in the fixtures but their TypeScript is held to a recorded list of hashes, so that changing, removing, or adding one fails until the list changes too, on purpose (pinned-files.test.ts). From the first stable release that list only grows: every line it had in a release must still be in it, unchanged, which a check compares with the release's immutable tag (pinned.ts, tested by pinned.test.ts). So a change to a pinned file fails even when its line is changed to match.
- Moving a stroke by whole units moves its outline exactly, over seeded strokes built to turn on a tie (outline.test.ts). In Obsidian, on seeded drawings, a separate mark that moves saving's crop changes no pixel when the strokes keep their place on saving's canvas, as with a mark to their right, or a stroke past the image's left edge such as a pen line with its far end erased. Otherwise it leaves no pixel more than 16 levels of 255 away. The same drawings save again unchanged (format.e2e.ts).
- In Obsidian, saving a symbol again after reopening it gives the same bytes, however far the drawing sits from the origin, and the pixels the browser decodes are exactly those encoded (ink.e2e.ts).
Pictures open
- Synthetic opaque pictures, at two sizes, in test/fixtures/pictures, open as a base layer of their own pixels, pixel for pixel, scaled to the line's height (ink.e2e.ts).
- Pictures without a record, transparent ones, and pictures one or two pixels high open from their pixels, and a record from a later version or one that cannot be used is not opened (the same file). The editor says why a file with no strokes opened as a picture, and says nothing of one whose record holds none (opening-symbols.e2e.ts).
- A picture to trace over, chosen with Choose picture… from a folder outside the vault, shows on the drawing area, and puts no file in the vault (choose-picture.e2e.ts).
Symbols read as characters
- In Live Preview and Reading view, in light and dark themes, a symbol stands on the text's baseline, as tall as the line box, and its pixels take the text's colour, measured from screenshots of the symbol in Obsidian (render.e2e.ts).
- The same holds in callouts, tables, embedded notes, hover previews, canvas cards, and popout windows; symbol files on their own and images from outside the vault stay pictures; and with Inkline disabled, symbols are plain images (the same file).
- Symbols saved as Inkline saves them, ending on the baseline, at 44 places across eleven lines of typed text, stand on the baseline of the letters beside them, measured in screenshots to a fraction of a pixel: within a quarter of a pixel, and of each other, in 16-pixel text at 100% and 150% and zoomed to 200%; within 1.2 pixels, and of each other within 0.6, in 13-, 17- and 20-pixel text, at 75%, and in 17-pixel text zoomed to 200%; and within 1.2 pixels, and of each other within one, in 16-pixel text zoomed a step in and out, to 109.5% and 91.3%, and two steps in, to 120%; in Reading view and Live Preview, in the text colour and its stored colour. In a box a snippet makes wider, the ink stays whole at the line's height, at the box's left (baseline.e2e.ts).
- Native PDF export, through Obsidian's real command and PDF writer: the output is rasterized independently with Poppler, and its pixels prove the symbol's size, baseline, text colour or stored grey, configured scale, and explicit sizes. Ordinary pictures stay pictures, and the temporary window's renderer settings are cleared on close. The test redirects the save dialog and suppresses the post-export viewer launch; the native PDF writer still runs (pdf.e2e.ts).
- A symbol 4,000 pixels wide at the largest Symbol size, wider than its space, keeps the proportions it was drawn in, within 5%, its baseline on the text's, and its colour, in Reading view, Live Preview, table cells in both, an embedded note, and a hover preview, in the text colour in light and dark themes, and in its stored colour in the light theme, as nothing Inkline does in the stored colour depends on the theme, measured from screenshots (wide.e2e.ts), and in a native PDF, in a heading where it is wider than the page, measured in the rasterized page (pdf.e2e.ts). So does the same symbol with an explicit size of 1,000 pixels across, wider than each of those places, in each of them and in a native PDF, where its ink ends on the baseline of a numbered list's number beside it.
- Saving refreshes existing placements in Live Preview, Reading view and popouts, preserving note text, explicit widths and unrelated images. Names with spaces, percent signs and Unicode are covered, as are repeated file timestamps (refresh.e2e.ts). In a popout and in a canvas card's own editor, a reshaped symbol's width over its height, and an explicit size's drop, follow its new shape, and a note first shown in a popout has its symbols measured (the same file). So they do in a card's editor whose frame never reaches Inkline with the focus, where a double-click on a symbol opens it, and whose document stops being watched as the editor closes. A symbol's images taken out of Reading view while it is rewritten with the same modification time come back, as the same elements, with its new picture, while one given a newer address meanwhile keeps it. An image taken out while its symbol is rewritten, then deleted and made again with its old modification time, comes back with the new file's address, not the address of the deleted file's last refresh, so that it does not show the deleted file's last picture (the same file). An embed that Obsidian makes anew with an address from before a change keeps that address, as the rendering contract says, and that case is not tested.
The editor shows what its tools do
The brush circle follows the nominal tool size and drawing-area scale. Pen and Eraser keep separate sizes, including through Next. The close button stays clear of the name field, and the drawing area's accessible name produces no hover tooltip, for three times as long as a button's tooltip took to show, at least 1.5 s (editor-feedback.e2e.ts).
Each font line is drawn in its own colour from the theme's CSS custom property, in light and dark themes, read back from the drawing area's pixels; turning a line off in the settings removes only that line, and G hides and shows the rest (guide-lines.e2e.ts).
The status line empties for each key, button, stroke, or typed name with nothing to say, as for Fit after "Zoomed out", and for a threshold moved after "Polygon dropped" while Make ink is open; what one says replaces what was there; a key that does nothing leaves it; and "Saving…" and "Draft not kept" stay through strokes and keys with nothing to say until the save ends or a draft is kept (status-line.e2e.ts, with its rules in status.test.ts).
Help explains the drawing tools and guides, closes with Escape, and restores focus to drawing without changing its strokes (editor-feedback.e2e.ts).
The brush replaces the native crosshair only while visible. Leaving, cancelling, and Help restore the fallback cursor; the indicator never enters saved strokes (the same file). These host checks do not establish subjective pointer comfort.
The fixed bitmap has a centre dot at every brush size, and retains its coverage across fractional positions at two editor widths and five zoom levels (brush-cursor.e2e.ts). Contrast checks cover light, dark, grey, coloured and translucent backgrounds, ink edges, stationary theme redraws and readback failure recovery (cursor-contrast.e2e.ts). Three fixed rounds of 300 pointer updates at 200% zoom must have a median below 5 ms per update while preserving the bitmap's coverage. This bounds the sampling cost in the Linux host harness; it does not measure physical-input latency or establish performance on every device.
Ink shows under the pointer that drew it, within 0.8 CSS pixels, at the top, bottom, left, and right of the drawing area, measured in a screenshot's pixels, in the usual view and after Fit in Zoom, at 100% and 125% page zoom, and the drawing area's content box, which its pixels fill, is as tall as the line box it shows (pointer-alignment.e2e.ts, #359).
Make ink of a synthetic H, enlarged from about 1.2 to 11.5 times, leaves at most two partly covered document pixels at each edge of the saved symbol, and the reopened symbol draws the same pixels. The editor's own redraw, which leaves scaling to the browser, differs from them only at pixels an edge crosses, and each run checks that this would catch the same row blurred or moved by a pixel (conversion-clarity.e2e.ts). So does a dim H of soft strokes, 42 levels from its ground to its ink, enlarged from about 2.4 to 7.7 times, and the surface shows at most three document pixels at each edge in the preview, zoomed in, and once applied. Unit tests pin the finer sampling, its alpha weighting, the threshold ramp it narrows for large enlargements and for little contrast, and its bounds of a million samples and a base layer's sides (pixels.test.ts). At every position of the slider, no pixel of a synthetic picture gains ink as it moves away from the ink, and no edge is softer than the contrast there alone would make it (threshold-ramp.test.ts).
Each brush size, drawn with a mouse and measured in the saved symbol, is as wide as its size. M is within 15% of the stems of regular text, L lies between 1.3 times regular and 1.1 times bold, and XL is at least about as heavy as bold, for the editor's text font and, where the host has them, DejaVu Sans and Noto Serif. In a note in reading view, in light and dark themes, an inline symbol's M strokes show within 20% of the text's stems on the screen. Five M strokes a grid spacing apart stay separate (pen-weights.e2e.ts).
A filled polygon, and a filled ellipse, read back from the drawing area's pixels, have exactly the outer edge of the same shape unfilled across the same corners, and everything within it is fully inked; with the eraser, an ellipse's hole reaches exactly as far as the eraser's line does. The pen's polygon on its first corner and ellipse being dragged show exactly what the click or the release leaves, and one Undo takes all of it back (fill.e2e.ts). Unit tests pin that a filled shape records its fill and the line of the shape unfilled as one step, and that a reopened drawing's grid goes by the shape as if unfilled (session.test.ts).
A view that adds each stroke to what it has drawn and measured shows what a new view does, pixel for pixel on the surface and in the preview, at full size and at 16 px, and the image's ends are exactly those of a full measurement, and within a pixel of what a save crops to (#159). A seeded run checks this after every frame, through strokes of each shape and tool, flat ends, undo, redo, clearing, moving the drawing, saving, restoring, base layers, panning and zooming, on drawings wider than a tile and with strokes across a tile's edge. The preview in text also stays as it is as a stroke starts (long-drawing.e2e.ts).
The eraser, drawn freehand along, across, and through a filled ellipse's edge, back on itself, and round a loop, with Zoom off and on, takes away exactly what its brush sweeps. In every frame read back from the drawing area while the pointer moves, the area shown is a redraw of the points reported so far, to within 2 of 255 in every pixel; no pixel more than a pixel inside where the brush had been gets back 64 of 255 or more of its ink; and more than a pixel outside the brush's circle no pixel gets back 128 or more. The release, and a redraw of the strokes the editor keeps, change no pixel by more than 2 of 255; and of the ink there was, none (128 of 255 or more) is left more than a pixel inside the brush's sweep, and none taken (below 128) more than a pixel outside it. The ink in the middle of the loop stays (eraser-sweep.e2e.ts, #341). The same check fails on every case with the eraser as 1.0.1 saves it. Unit tests compare the area with the brush's exact sweep along straight lines, sharp turns, turns straight back, zigzags, a mouse's whole-pixel steps, a figure eight, random walks, and a loop round an island, check that it never takes back what it swept as points come, and never goes out and back along itself (sweep.test.ts). Others check that a seeded run of strokes keeps whole units; that an eraser stroke drawn freehand is a fill from its first point on, never cut, unless it starts with Flat ends and the grid both on, when it is shown and saved as the pen's stroke through the same drag, as 1.0.1's eraser's was; and that a drawing saved by 1.0.0 opens on the grid 1.0.1 guesses for it (session.test.ts). The eraser's area shown is the one that letting go, or Next, or a lost capture saves, whatever the release says of Shift, as of a key the editor missed: in seeded drags whose Shift and grid change between moves, in a test for each of Shift, the grid, a grid laid out anew, and Flat ends changing with the pointer still (the same file), and in Obsidian for Shift pressed and the grid turned on with the pointer still, where the release changes no pixel by more than 2 of 255 (flat-ends.e2e.ts).
Drawing is never lost
- The close question, saving from it, a failed save that keeps the editor open, strokes drawn while a save runs, and a stroke still being drawn when saving (saving.e2e.ts).
- A new symbol whose note was deleted saved by Mod+S, Save, Next, and the close question, with a notice that it was not inserted, and saved again without it; one whose note was deleted after it went in saved and renamed, with Next starting no other; a note put at the deleted one's path, while a restored save read it or as the embed was written, left as it was; a new symbol with nothing drawn, or only the eraser's strokes, not saved by any of them, nor by clicks on Next that reach the next editor, while a symbol with a file saves when cleared (note-insertion.e2e.ts for the deleted notes, and saving.e2e.ts and next-symbol.e2e.ts for nothing drawn).
- Drafts: kept when Inkline is disabled, through a restart while a save writes the file, when the storage refuses one, offered to one editor at a time, and a first save that an interruption cut short finished from its draft (drafts.e2e.ts, interrupted-saves.e2e.ts, and drafts.test.ts). With Inkline disabled while Obsidian moves the file or asks about links, the draft kept for the file's new name once the save ends, and dropped without a question when the symbol opens holding all it holds; a stroke drawn during the save offered back, kept as long as it would have been; the draft kept, on its own base layer, and offered when the file changed meanwhile or after, elsewhere or by Inkline enabled again, and restored with its strokes and picture; and a draft that Inkline, enabled again meanwhile, restored or dropped as expired, and one that expired, never brought back (rename-while-disabled.e2e.ts). A draft that would restore nothing its file lacks dropped, and one that differs in any stroke, its picture or its place, its name, or text typed, offered (drafts.test.ts).
- A symbol whose file was cut short after its draft was kept does not open, and its notice says the draft is kept; a new symbol given its name, once the file is deleted, and moved into its folder, offers the draft, which brings back its strokes but not the file's own base layer. A symbol renamed while Inkline is off offers its draft once renamed back, and not before (opening-symbols.e2e.ts and drafts.e2e.ts).
- A draft's base layer dropped from storage as soon as the draft that replaces it is kept, and never before: kept when storage refuses the replacement, and while another draft names it, a held one, a restored one, or another editor's; and stored once when a stroke keeps a draft while it is being stored ahead of a save. With room for two pictures in Obsidian's own local storage, a draft is kept through copy after copy (base-memory.e2e.ts and drafts.test.ts).
- A draft that a newer version kept, in a layout this version cannot read, kept as it is, with every base layer it names, through opening its symbol, which says that it is kept and offers nothing, this version's own draft for the symbol and its save, a rename, and storage refusing this version's drafts, and dropped only once its lifetime ends; and a draft as 0.9.2 to 1.0.0 stored it offered back (drafts.e2e.ts and drafts.test.ts).
- A decoded base layer kept while Undo or Redo can reach it, and shown again by them, and let go after a new change past an Undo, by a copy or a stroke, and once it is further back than Undo goes (base-memory.e2e.ts).
- A file changed on disk while the editor is open: taken in, asked about, reloaded with the drawing one undo away, never saved over when it cannot be read, and saved again where it was if deleted (file-changes.e2e.ts and disk.test.ts).
- A change to a symbol's text alone told from a change to its drawing, byte for byte: taken in without a question, by the library's save or a change on disk, with unsaved strokes, Undo, and a draft's lining up left alone, and on top of a change Keep mine replaces; found as a save starts, which goes on, through Next too; and text typed in a field the file changed kept, with what saving replaces shown, and a save that finds that first writing nothing (symbol-text-on-disk.e2e.ts, text.test.ts, and disk.test.ts).
Text it was not asked to change stays as it was
- The link scanner, which reads links as Obsidian does, with a randomized test that an insertion never lands inside a link and moves nothing outside one (links.test.ts and insertion.test.ts).
- In Obsidian: a symbol goes after a link, an embed, or an address the cursor was in; into the note it was started in, through its live editor or its file; and found again after the text moved (note-insertion.e2e.ts). Type to insert lists nothing in code or front matter, and the links it writes lead back to their symbols, from a note in a folder too, as paths from there when Obsidian writes relative Markdown links (suggest.e2e.ts). What it counts as code is checked in unit tests against a set of synthetic notes, each as Obsidian renders it, which a test in Obsidian checks, and against CommonMark for every short note of a set of lines on which the two agree (code-cases.ts, code.test.ts, and suggest.e2e.ts).
- The cursor lands after a symbol from every route that inserts one, and typing goes on there: Save, Mod+S, a run from Next, both lists, and the library, past a link or an address, after the note's changes moved the place or took it away, in the pane the symbol started in or the one that took it, and through a rename, however Obsidian's question is answered. The same holds in a table cell in Live Preview, with real keys, including when a change on disk takes the cell's editor away. A selection's text stays, one undo takes the symbol back, and a discarded last drawing leaves the cursor after the run. A note in Reading view or closed takes the symbol through its file, whose line endings stay as they are while the place is found from either kind, in both directions, and Insert existing symbol places a symbol as the other routes do. A rename while the note holds unsaved text writes the new name once and keeps the text, however Obsidian's question is answered, in a plain note, two panes, a table cell, a closed note, and Reading view, with the cursor and the place of a run from Next surviving a reload, and with the text arriving during the question or an editor's own save falling due in it. Every rename, by Save, the library, or an existing symbol's editor, saves the open notes first, and is refused with nothing changed if one cannot be saved. A reload held past the editor's own save loses no text, and running out of time writes nothing (cursor-placement.e2e.ts, table-cells.e2e.ts, line-endings.e2e.ts, unsaved-text-renames.e2e.ts, library-renaming.e2e.ts, renaming.e2e.ts, and insertion.test.ts).
- Once Inkline is turned off, nothing it started acts: Insert existing symbol closes, and a choice that still reaches it inserts nothing, while a new one inserts once Inkline is on again; Edit symbol in a menu left open does not even read the symbol; a library rename or change of readings still waiting writes nothing, and says so, and the rename saves no open note; a rename waiting for Obsidian's index or another rename, in the library or an editor, stops at once, while one turned off during Obsidian's question about links finishes, with a new symbol's embed following it to the new name; and a layout callback that comes late, or turning Inkline off while it reads its settings, leaves no tagged symbols, display settings, menus, or commands behind, and the next load has them all (plugin.e2e.ts, library-quick-edit.e2e.ts for the change of readings, and rename-races.e2e.ts and renaming.e2e.ts).
- Names and renames: what a file name cannot hold, names a folder already has, renames that fail, names given elsewhere during saving or hashing, and the reported outcome when an external rename follows a successful native rename (names.test.ts, naming.e2e.ts, renaming.e2e.ts, and rename-races.e2e.ts).
- Keyboard focus before the editor's first animation frame, and intentional name-field typing across that frame (drawing.e2e.ts).
- Edit symbol only where the cursor or the pointer is on a symbol, in every entry point (entry.e2e.ts).
- A right-click on a symbol offers Edit symbol, once, and opens that symbol, in callouts and tables in Live Preview, in canvas cards focused or not, in a note on a canvas, in several selected cards, in a popout window, and in a text card's own editor, where the command works too; the block's own menu keeps its items and works, on the symbol and off it; a card over a symbol adds nothing; and if the canvas's sheet over a card is renamed, its menu stays as it is (symbol-menus.e2e.ts).
- A double-click on a symbol opens that symbol in the editor, once and without Obsidian's image viewer, in Live Preview, a table in it, a popout window, a canvas card that is not focused, instead of the card's text, a note on a canvas, and a text card's own editor. The first click still puts the cursor at the embed, and a click on the selected symbol later does what it does on a picture. A double-click on a picture, on words, beside a symbol on a card, in Reading view, an embedded note, a hover preview, a focused card, or a callout in Live Preview opens no editor, and once Inkline is off nothing answers one (double-click.e2e.ts).
- The library lists symbols and their referring notes, filters by name and folder, follows file and link changes, and inserts successive symbols without replacing selected text or splitting a link (catalog.test.ts and library.e2e.ts).
- A click in the library lands when the list has something to redraw between its press and its release: a new symbol, values the index read, a row a filter found above the one pressed, Show more, and a form closing. The redraw follows once the press ends, inside the list or out of it, in a popout window too, and a press whose release never came stops holding it back at the next move (library.e2e.ts).
- A symbol's readings and translations: typed in the editor and saved with a new symbol, shown on opening again, kept through later saves and in a draft, and refused over the format's limit; changed from the library with every chunk but their own as it was, byte for byte, no note touched, on a file with no record, a damaged one, or a list Inkline cannot read, which stays; a file that is not a whole PNG left alone; a change on disk followed, warned of, or asked about, and never written over unseen; a value at the limit, and bidirectional controls kept to their own value; a name and a reading that disagree, through a rename; and Copy from leaving them behind (symbol-text-editor.e2e.ts and symbol-text-library.e2e.ts).
- Two saves of one symbol that meet, with each held between its read and its write: two from libraries keep both fields, or refuse the later of two to one field with what is there; a library's that goes first stops an editor's until it asks; and an editor's that goes first has the library's build on it. None is lost to a file renamed, or deleted and put back, while a save waits, with saves asked for under the old name and the new, and two editors saving a deleted file make it once, with the other asking. A change that lands during a save is seen by the bytes, not by a date or a size. A program outside Inkline that writes after the last read is a limit, which this does not cover (file-writes.test.ts and symbol-text-concurrent-saves.e2e.ts).
- A symbol deleted, and another file put at its path, through Obsidian while a save reads it for the last time, by its file system, as another plugin or a sync tool can, or by its vault: Quick edit refuses the save and the new file keeps what it holds, and the editor asks about it. A write that lands once the file was replaced says so, and keeps what was typed. A save waits for what was asked of the disk during its last look, and writes as before once the disk stays busy, or where Obsidian's line of disk operations cannot be seen (write-identity.e2e.ts and file-writes.test.ts).
- A write Obsidian does not finish, held back in the host: a save that takes less than the wait shows nothing; a save behind it in the library says so after the wait, keeps what was typed to copy, and finishes when the write does, while Cancel or Esc leaves it and it writes nothing; a form whose own write is held closes and says it may still finish; the editor says its strokes are in a draft, unless none could be kept, goes on drawing, and gives them back after a restart. However long a write takes, no save behind it reads or writes (symbol-text-unfinished-writes.e2e.ts and file-writes.test.ts).
- A rename Obsidian does not finish, with its own move, a note's save, or a link's update held back in the host: nothing is said during Obsidian's question, however long, or of a slow rename that keeps moving; one held says so after the wait, counted from the answer if there was a question, keeps the name to copy, and ends with the rename; the message goes if the question opens late; Cancel or Esc leave it, a rename not begun is stopped, and one begun says that it may still finish, and how it ended; another rename of that symbol is refused until then; a failure gives the form back; and the editor does the same (library-renaming.e2e.ts, renaming.e2e.ts, and file-writes.test.ts).
- The insert trigger's list, Insert existing symbol, Copy from, and the library's filter find a symbol by a reading or translation whatever its name, and show why; the index follows files as they are made, changed, renamed, moved with their folder, and deleted, lets a search work while it reads, and finds what just changed before the rest (symbol-text-search.e2e.ts). All of them search alike: an accent needs no typing, and a mark that makes another sound counts, in kana, Indic scripts, Thai, Arabic, Hebrew, and Cyrillic (search.test.ts), and the index goes on past a damaged file and a costly one (text-index.test.ts).
- Names line up in the insert trigger's list, Insert existing symbol, Copy from, and the library, in both themes: every name and folder starts at the same x, at the ends of the Symbol size setting, and beside a very long name or a picture that will not load. A symbol as wide as the editor's surface, or wider, shows whole and in proportion, in the text colour and its stored colour (symbol-lists.e2e.ts).
- With Obsidian's interface in Hebrew, which mirrors its layout, each of those lists puts a narrow symbol's picture right of its name and its ink in the right half of the column, in the text colour and its stored colour, and in English left of the name and in the left half, as before. In both, the editor's, its Help's, and the settings' English keeps each sentence's words and its full stop or ellipsis in English order, the preview's symbol stays between its words, and in Hebrew the editor's layout is still mirrored and its text on the right (right-to-left.e2e.ts). A toolbar button's tooltip, a symbol's name as its tooltip, and another plugin's tooltip keep their closing bracket at the end in Hebrew too. In Hebrew, Inkline's notice keeps its full stop at the end, while another plugin's English notice still puts it at the start, and in English both keep it at the end (the same file).
- In the library, in both themes, the list never scrolls sideways, in a sidebar from the narrowest Obsidian allows to a wide one, with 90-character names with and without spaces, a deep folder, and wide symbols. In the default sidebar every row keeps its name and buttons on one line, even beside a scroll bar, and a mid-length name shows whole. A shortened name and folder are whole in a tooltip, and a long-named row's buttons, the filter, and renaming work (symbol-lists.e2e.ts).
- Renaming in a library row: links follow, PNG bytes stay identical, names in other scripts work, errors keep the entered name for retry, a deleted and replaced file is refused, and repeated submission starts only one rename (library-renaming.e2e.ts).
- Quick edit in a library row saves a name alone, with links following and the file's bytes as they were, readings and translations alone, with no note touched, and both with one Save; with nothing changed, Cancel, or Esc, it writes and renames nothing. A name another symbol has is refused before anything is written. A rename that fails after the readings were written keeps them saved and the name to try again, which then renames without writing them twice, and so does a symbol renamed elsewhere while they are written, which is not renamed again; a rename that something came between says only that they are saved. A write that fails, or that finds the file changed, renames nothing; a save left while its write waits renames nothing, and one left while its rename waits says the readings are saved. With Inkline turned off during the write or the rename, a notice says what was and was not done. A name nobody changed follows renames made elsewhere, one after another, and never renames the file back; a name typed stays through them, and a refused name's reason through a change to the file. Quick edit fits the narrowest sidebar with a long name, and the list and Quick edit keep their names for screen readers with no tooltip over their empty space. The row's own Quick edit says that its form is open, and closes it as Cancel does, by click, Enter, or Esc, dropping what was typed and keeping the focus, and only the first click of a double-click opens or closes it. A row closed by Esc during a press on its Quick edit keeps its form until the press ends, and that form saves nothing; the release, a click on the same Quick edit, opens no second form, and nor does another row's Quick edit from the keyboard meanwhile. It is unavailable while Cancel is, during a save. A save left with it renames nothing, shown with Esc while the write waits, or says that the readings are saved, shown with a click while the rename waits; every way of leaving ends in the one handler, so each way and each step is shown once. Shift+Tab from the name reaches it and then the symbol, past Uses, and the row's buttons follow a rename made elsewhere, into another folder. Its symbol shows the file's menu, and its fields do not. What each outcome writes, renames, and says is also unit-tested (library-quick-edit.e2e.ts, library-renaming.e2e.ts for a name alone, symbol-text-library.e2e.ts for readings and translations alone, and quick-edit.test.ts).
- Measured in both themes, each row's readings and translations, and the notes Uses lists, are 4 px below the row's buttons and 12 px above the next row, with no space between them, where a row with neither is 8 px from the next. They start at the row's edge, at the size of Quick edit's labels, with their labels and Uses: in bold and the notes bulleted, and the notes open, in a new tab with Ctrl. While a row is in Quick edit, the other rows' Uses and Quick edit, and Show more, are disabled, keep their names for screen readers and say why, and leave the focus in the form when clicked, while a symbol still inserts; once it closes they work again, with no click kept from meanwhile. Quick edit's fields open fitting what they hold, grow a line at a time from two lines to eight and shrink back, fit a line that wraps, and keep a height they are dragged to, by
field-sizingon Obsidian 1.15.1 and by script on installer 1.5.8, to the same heights. A row in Quick edit keeps its symbol, Uses and Quick edit where they were, and the form takes the place of what shows under them, 4 px below the buttons and 12 px above the next row, across the row, with the name's field as wide as the others; the row's Uses waits with the others', its Quick edit shows pressed, with Obsidian's focus ring when the keyboard reaches it, and its symbol still inserts (library-look.e2e.ts and text-fields.test.ts).
Preferences are kept and apply where they are shown
- Validated defaults and saved values, including invalid data (settings.test.ts).
- The real settings tab, immediate trigger changes, drawing defaults after reload, stored-grey pixels and explicit sizes, new and existing popouts, ordered writes, write failures followed by recovery, and malformed settings (settings.e2e.ts).
- New symbols follow Obsidian's place for attachments, in the vault's top folder, the note's own folder, and a folder of its own, with no symbol folder set; with one, they go there through Next, nested folders are made, a folder there in other letter case is used, and a file in the folder's place stops the save with the drawing kept, which saves once the file is gone (symbol-folder.e2e.ts). Unit tests refuse folders that leave or hide from the vault or break a name (names.test.ts).
The keyboard reaches everything but drawing
- Each control is labelled, its tooltip shows its key, toggles say whether they are on, and keys give way to a text field (buttons.e2e.ts and drawing.e2e.ts).
- This site lists every command and every button's key as the code has them (docs.test.ts).
It stays quick
Each of these asserts a budget beside its correctness checks:
| What | Budget | Where |
|---|---|---|
| Tagging a thousand symbols in a note, the fastest of five runs | 50 ms | render.e2e.ts |
| Searching 5,000 symbols as each letter of a name, reading, or translation is typed, each query's fastest of three | 100 ms | scale.e2e.ts |
| Keeping a draft with a large base layer, after the first | 50 ms each | drafts.e2e.ts |
| Previewing the ink of a 4K screenshot | 300 ms | ink.e2e.ts |
| Saving, without waiting for the window to be idle | 700 ms each | saving.e2e.ts |
| The longest task and frame of saving nearly the largest file a symbol can be, the shortest of three | 400 ms | save-responsiveness.e2e.ts |
| The same for a symbol of the most pixels it can have | 200 ms | save-responsiveness.e2e.ts |
| The longest task and frame of opening nearly the largest file a symbol can be, the shortest of three | 250 ms | open-responsiveness.e2e.ts |
| The same for a symbol of the most pixels it can have | 300 ms | open-responsiveness.e2e.ts |
| Adding a pen stroke to 3,000 dots, and a frame of one past the image's end, the fastest of nine | 30 ms each | long-drawing.e2e.ts |
| Reading long lines of failed links in one pass | 3 s each | links.test.ts |
A budget alone would not show that a large symbol is read in slices, as a canvas can put off the work it is given and leave it for a later call. So open-responsiveness.e2e.ts also counts the other tasks that run all through a read, compares what it finds with the plain steps, its pixels with one whole draw, and holds a read up to act meanwhile: asking again, another window, a change to the file, closing, and drawing while Copy from or Reload reads.
A release is what was tested
- A release is refused unless the commit's required checks, the end-to-end tests in both Obsidian versions included, passed within the last week (publish.test.ts).
- Before publishing, the release's own files are installed in Obsidian, in the oldest and the latest version, and must be those files byte for byte, load with their version, commands, and styles, and save a symbol (package.e2e.ts). Direct CI checks the loose build in
dist/; Docker and release preparation check the plugin extracted from the install ZIP. - The explicit release update check starts from the previous published ZIP, draws and saves a preference, then installs the new verified ZIP. It checks the drawing bytes, note and preferences survive replacement and reloading, that the symbol still shows in the note, that both tools start with the configured size, and that a stroke drawn over it and a new symbol save and reopen. From a release before 0.9.2 the symbol opens as a picture and says why, as the owner decided in #144; from 0.9.2 on it must open with its strokes, or the check fails (update.e2e.ts). It also leaves the old release's editor open with an unsaved stroke: from 0.9.2 on the draft must come back after the update and save both strokes, and from an earlier release it is dropped. This runs separately from ordinary CI because it needs both release artifacts; the release PR records its inputs and results.
- Installing and updating through BRAT, an optional third-party route, has a separate check against the published releases. BRAT's own dialog installs the highest release and a chosen one, downloading only the three plugin files, and an update from one to the other keeps the drawing, note and preferences. From 0.9.2 on it keeps the strokes and an open drawing's draft too; from an earlier release the symbol opens as a picture and the draft is dropped (brat.e2e.ts). It needs BRAT's release and GitHub, so it is run by hand and gates no release.
- A publication that fails part way can run again without replacing anything published: each failure is run against a fake GitHub (publish.test.ts), and against a fake of the GitHub CLI, with the exact commands that publish a public release and a pre-release (publish-cli.test.ts).
- From 0.9.4, each release carries a copy of the file format. Publishing refuses one that is not the tagged commit's document byte for byte, or whose name does not give its version and revision (publish-cli.test.ts), and after publication the workflow compares the downloaded copy with that document and verifies its attestation. The document links only to its own headings and to full addresses, so that the copy reads on its own (docs.test.ts).
- A public release that cannot be published can be rolled back and resumed: the release guide's own commands run in a synthetic repository, and each state passes the checks CI runs (rollback.test.ts).
What this site and the repository say agrees
- A public release's package and manifest versions agree and it has a matching compatibility entry in
versions.json, a pre-release's version reaches neither file, though a build's manifest names it, the manifest names the newest public release,versions.jsonlists exactly the public releases the changelog records, and each release has its changelog section (release.test.ts). - A new version is higher than every published one in SemVer's order and in Obsidian's (version.test.ts).
- This site's commands, keys, defaults, Obsidian version, links, and example embeds agree with the code, as do the links, Obsidian and Node.js versions, command names, and examples of the repository's own documents, and the versions its BRAT recipe names (docs.test.ts), and what deploys follows Versions of this site (docs-source.test.ts).
- Since 1.0.0, none of the home and install pages, the README, and Known limits says that Inkline is a pre-release, that every release is one, or that there is no release yet, public or of any kind (docs.test.ts).
Checks shown to fail
A check is stronger evidence when it fails on deliberately broken behavior or on the code before a fix. The pull request that adds or changes a check records that experiment and its limits. Earlier examples are in the verification work linked from #46; the individual pull requests hold the inputs, results, and review discussion.
Limits of this evidence
- The end-to-end tests run on Linux only. The unit tests and the build also run on Windows; Obsidian on Windows and macOS is not tested.
- Drawing is tested with WebDriver's mouse and synthetic pointer events, not with real devices. Drawing tablets and touchscreens are not supported beyond drawing as a mouse does.
- Refresh checks outside the symbol editor use Obsidian's
vault.modifyBinary; they do not exercise operating-system file changes through its file watcher. - Obsidian's mobile apps are not tested, as Inkline does not support them.
- Physical printer output is not checked. Native PDF export is covered on Linux with default and explicitly sized embeds of one symbol, and one wider than the page; long notes containing many different symbols are not covered by that fixture.
- CI's runners have the DejaVu fonts, and the Docker image DejaVu and Noto; a theme's own font is checked through the guides' measurement, not by eye.
- The release workflow checks the install ZIP's exact layout and bytes, extracts it with the system archive tool, and tests the extracted plugin in both real Obsidian hosts. Windows unit checks also extract a synthetic package with PowerShell. After publication, the workflow verifies downloaded checksums and attestations, then extracts the published ZIP and compares its files with the loose assets. This verifies our manual installation channel. It does not audit or endorse third-party installer plugins.
- Memory is checked as whether anything can still reach a decoded base layer once garbage is collected, not as how much memory Obsidian or its GPU process uses.
- The budgets are wall-clock times. Each leaves room for a slow machine, but heavy work beside a run can still exceed one; such a failure is investigated, not run again until it passes.