Repository navigation
Releases
v0.3.2 — reliable folder taps and safer builds
Folder shortcuts now ignore taps made in other apps and menus, keep links to empty folders working, and choose the intended link when tap rectangles overlap.
- Navigation: require a gesture to begin on the visible note, suppress overlays and their dismissing taps, and pause page reads outside the note or after the note closes (#11, #13).
- Input: deduplicate raw/SDK reports before claiming a tap, reject palm-size and nonfinger contacts, and limit the raw fallback to the verified portrait Manta panel (#14–#16).
- Links: retain empty-folder destinations, choose hits by containment and distance, and remove pending copies when overlapping native links confirm persistence (#12, #17, #18).
- Builds: stop packaging on native build failure, remove stale outputs, and discover conventional Linux Android SDK installs (#19).
- Development: verify a fresh matching build stamp without clearing logs and keep debug bundles outside cloud-synced MyStyle. Firmware that ignores DEBUG reloads now produces an actionable failure (#10).
Install the attached SupernoteFolderShortcuts.snplg through the Supernote plugin manager. This update changes native code and requires a full package installation. Grant file read/write access if prompted; Always allow keeps shortcuts available after the picker closes. Chauvet builds 2609111001 and 2610191001 do not hot-load DEBUG bundles.
Validation: all 139 automated tests, lint, TypeScript, and the full Android build pass. Physical Manta testing on Chauvet 2610191001 confirmed single finger navigation, normal file-manager behavior, persisted empty-folder links, palm rejection followed by a normal finger tap, and in-note menu dismissal. Regression CI passed.
Compatibility: validated on the Manta (A5 X2). That device reports Supernote_Nomad in Android; this does not constitute Nomad testing. A physical Nomad (A6 X2) beta check is still pending, and Nomad compatibility is not yet claimed. Use the Nomad checklist and report template and submit results to tracking issue #21.
The attached SHA-256 file verifies the package. Fix commit: f1edca8.
v0.3.1
Chauvet 3.29.43 compatibility release, verified on a Supernote Manta A5 X2 (which may identify as a Nomad over USB).
- Restores the folder picker and link taps on Chauvet 3.29.43. The firmware
now blocks shared-storage reads and writes until a plugin declares and
requests them. Folder Shortcuts declaresFILE:READandFILE:WRITE, asks
for both when the picker opens, and keeps folder browsing/link creation
disabled with an actionable message until access is granted. - Missing permission no longer floods the native page reader. Background
scans stand down when read access is absent or error 1503 reports that it was
revoked, then resume as soon as the picker receives authorization. - Large notes no longer discard a tap that overlaps their page scan. The
ordinary two-second stale-tap guard remains fixed, while a known in-flight
scan uses that page's measured duration plus the same safety margin. Context,
input, and picker-state checks still reject taps after the user moves on. - The package is built against
sn-plugin-lib0.1.65. A clean dependency
install is required before packaging so the bundle reports the SDK expected
by the.43plugin host.
Install the full .snplg from Settings → Apps → Plugins → Choose Installation Package, then grant file read/write access if prompted.
v0.3.0
The tap path is rebuilt. Links are hit-tested against the note as it stands at the
moment of the tap, instead of against invisible windows laid over each link, and a
narrow read-only raw-input fallback covers the firmware cases where the SDK stops
reporting complete gestures.
Validated on a Manta A5 X2: stylus and finger taps each open their folder, and a PDF
or EPUB excursion followed by Last Opened Note and an immediate finger tap
navigates correctly. Nothing about how links are stored has changed since 0.2.0, so
upgrading is a straight replacement.
Linked objects can be moved and stay tappable
The invisible overlay windows swallowed finger events, so a linked object could not be
dragged at all, and their rectangles came from the last refresh, so the tappable area
stayed behind whenever the object did move. Taps are now hit-tested against the live
page, which makes the clickable area the link's own rectangle by definition and lets it
follow the object.
A lasso move is not published until the rectangle actually changes. While a moved
object stays selected the Note app can keep returning the old rectangle, or briefly
return fewer links. The page is held dirty until it settles, the old hit area is
preserved if the move is cancelled, and that dirty state survives a document excursion
so the first tap after returning uses the committed moved rectangle.
The first tap after a PDF or EPUB no longer disappears
Manta firmware can hand the SDK listener only an orphan UP after returning from a
document, and can suppress a raw touchscreen axis whose value did not change. A
read-only raw-input fallback retains the absolute axes across that handoff and feeds
complete single-finger taps through the same context, scale, ownership and hit-testing
guards as SDK motion events. It accepts single-finger taps only and does not modify the
firmware's own monitor.
One slow read cannot block every later refresh
Context reads have a two-second deadline driven by an Android Handler, which keeps
running while Supernote pauses JavaScript timers. Context probes run independently of
page reads, page reads are single-flight, and a clean tap miss no longer starts another
full-page scan.
Fewer ways to lose a tap
First reads wait for the native page rather than only the reported path, after hardware
traces showed provisional empty pages at 531ms and 1026ms with the note finishing its
load at 1525ms. PEN_UP payloads are recycled so the native element cache cannot fill
and blind the plugin. Tap claims can only be released by their owner, including when an
input handler throws. Page scale is not treated as measured until the SDK probe
succeeds. The folder picker has an owner-stamped single-flight guard, so rapid presses
cannot create duplicate links and delayed work from an old picker visit cannot close a
newer one.
Known limitation
On very large pages a full scan can take around twelve seconds, which is well past the
budget a tap is allowed to wait for one. A tap that has to wait on a scan there may be
dropped, and need a second tap. See #7.
v0.2.1
A maintenance release for the three problems reported in
#3, all of them
reproduced on a Manta. There is no firmware requirement beyond 0.2.0's, and nothing
about how links are stored has changed, so upgrading is a straight replacement.
The folder picker can be used more than once
Closing the picker does not unmount its view, so after one successful link the button
stayed greyed out and the "Closing…" message stayed on screen for every later visit,
until the device was restarted. The picker's state is now reset once the host has
finished closing, and again when it is next opened, so work started in one visit can no
longer apply its result to the next.
Links stay responsive after leaving and returning to a note
Tapping a link was unreliable in a way that looked random but was not: it depended on
how much was on the page. The plugin stopped listening for taps whenever the note
context read back empty, which is what happens during any excursion, including the one
the plugin itself causes by opening a folder. Coming back, it had to wait for a
heartbeat and then re-read the whole page, measured at one second for a light page and
over three for a busy one, and every tap in that window was silently discarded. A
heavier note meant a longer dead spell, which is why one note felt reliable while
another ignored half the taps.
A missing note context is now tolerated for a minute before the plugin stands down, so
returning to a note no longer costs a blind window.
Opening the picker no longer jumps into a folder
The tap that opens the picker from the lasso toolbar is itself a touch on the screen,
and the toolbar appears right next to the word being lassoed. That tap was therefore
being hit-tested against the note, and it opened the link underneath. Doing so threw you
into the file manager and destroyed the lasso, which is why the picker afterwards
answered the link button with
No lasso rect: {"error":{"message":"No Lasso action has been performed. …","code":904}}
Both symptoms were the same fault seen from either end. Navigation is now suppressed
while the plugin's own interface is up. The suppression is armed by the toolbar buttons,
kept alive by touches in the picker, expires by itself if the host takes the view away,
and leaves a short grace period after closing so that the closing tap cannot navigate.
When the lasso really has been lost, the picker explains how to retry instead of
printing the raw error.
Installing
Copy SupernoteFolderShortcuts.snplg to the device and install it from the Supernote
plugin manager, as with previous versions.
v0.2.0
Fixes both open issues, and replaces how links are stored and how taps are caught. Anyone on 0.1.1 should upgrade: on current firmware 0.1.1 does not work at all.
Requires firmware with the 3-argument plugin API
Chauvet 3.28.42 or later. On that firmware the host's NativePluginAPI.registerEventListener takes (id, event, registerType), while sn-plugin-lib@0.1.34 called it with two arguments. The resulting exception aborted JS init, so the plugin loaded, showed its buttons, and did nothing at all. This release moves to sn-plugin-lib@0.1.43, which matches the current contract. Older firmware on the 2-argument API is no longer supported; stay on 0.1.1 for those devices. (#1)
Links live in the note, not beside it
0.1.1 kept a sidecar directory of shortcut records and treated it as the source of truth. Nothing ever deleted from it, so removing a link left the shortcut firing, and a record from one note stayed live while a different note was open. Links are now read back out of the note itself, which the note app maintains, so removing a link removes the shortcut and a link belongs to exactly one page. (#2)
Linked objects can be moved and resized again
The finger path used invisible SYSTEM_ALERT_WINDOW rectangles laid over each linked word. Those swallow every finger event inside them, so a linked object could not be dragged, and their geometry came from the last refresh, so the tappable area lagged behind an object that had moved. They are gone: both finger and stylus taps arrive through the plugin's motion listener, and a tap is hit-tested against the link's own rectangle, which follows the object.
Other fixes
- Tapping a link no longer loops. A touch could be resolved seconds after the fact and applied to a screen the user had since navigated away from and back to. Taps now hit-test against the most recent read, and a touch older than 800ms is discarded.
- The plugin no longer goes blind after sustained use. Page elements are handed back to the native cache after each read, with a clear-and-retry recovery for a cache that is already full (error 206).
- Link state no longer goes stale while you work. The refresh is driven from the native side; React Native suspends JS timers whenever the plugin view is closed.
- A refresh could be superseded forever on a busy page, leaving taps unhandled there. Refresh passes now run to completion and are cancelled only when the plugin stops.
- A folder created after its link now starts working without a restart (the folder-vs-file probe cache expires after a minute).
- Pressing "Link lasso → this folder" twice no longer writes two links.
Known limitations
- Tested only on a Supernote Manta (A5X2). Scale is derived for other panels but untested; zoom is not handled.
- A link removed in the last few seconds can still fire once, until the next refresh.
- A very short deliberate mark inside a link's rectangle can still be read as a tap.
Install: copy SupernoteFolderShortcuts.snplg to /MyStyle/ on the device and install it from the plugin manager.
v0.1.1
Changes
- Folder picker ceiling raised to the Supernote storage root. The "up" arrow from
Note/now takes you toSupernote/, so you can shortcut to folders underEXPORT/,INBOX/,MyStyle/,SCREENSHOT/, etc. - Show Hidden toggle in the path bar. Dot-prefixed entries are filtered out by default; tap
[ ] Hiddento reveal them. - DPI-scaled finger-tap overlays. Page coords are now scaled to screen pixels using
DisplayMetricsand the SDK'sgetPageSize, replacing the previous 1:1 assumption. On Manta / Nomad the ratio resolves to 1.0 so behavior is unchanged; other Supernote models should get hitboxes in the right place.
Install: copy SupernoteFolderShortcuts.snplg to /MyStyle/ on the device and install from the plugin manager.
v0.1.0: initial release
Supernote Folder Shortcuts
A plugin for the Supernote A5X/A6X/Nomad/Manta that lets you turn any
handwritten or typed word into a one-tap shortcut to a folder.
Lasso a word, pick a folder from the plugin's file browser, and a native
link is attached to the word. Tapping the underlined word, with the pen
or with a finger, navigates the Supernote file manager straight into
that folder.
Usage
- In a note, lasso a word.
- Tap the 3-dots menu on the lasso toolbar → Folder Shortcuts.
- Navigate to the target folder in the picker, then tap
Link lasso → this folder. - The word is underlined. Tap the underlined word with the pen or
with your finger to open the folder.
To remove a link, lasso the word again and use the native 3-dots
menu → Remove Link (the plugin's size gate lets the lasso pass
through without opening the folder).
How it works
The Supernote plugin SDK can set a native link on lassoed strokes
(setLassoStrokeLink) but only supports linkTypes 0..4 (page / note
file / document / image / URL), and there is no "folder" linkType,
so tapping the native link does nothing on its own.
This plugin works around that by:
- Calling
setLassoStrokeLink(linkType: 2)so the word gets the native
underline. - Persisting a sidecar record of
{notePath, page, rect, folderPath}
inside the plugin's own data directory. Each shortcut is stored as
an empty directory whose hex-encoded name carries all the fields,
since the SDK exposesmakeDir/listFiles/deleteDirbut no
generic file-write primitive. - Pen path: listening for
PEN_UPevents globally. When a tap-sized
stroke (≤10 sample points) lands inside a saved rect on the current
page, the plugin deletes the tap's ink stroke and calls
FileUtils.openFilePath(folderPath). - Finger path: a native Android module installs a transparent
SYSTEM_ALERT_WINDOWoverlay over each linked word's on-screen
rectangle. The overlay consumes finger (TOOL_TYPE_FINGER) taps and
passes stylus events straight through, so writing/lassoing over the
linked region still works. Overlays are refreshed on a 1.5 s context
poll so navigating between pages/notes re-installs the right set.
A stroke-point discriminator lets lassoes pass through the pen path
untouched, so you can still use the native 3-dots menu on a linked
word to edit or remove the link.
Limitations
- Native link handler ignores folder paths. Without this plugin
running, tapping a linked word is a no-op. The plugin must be
installed and enabled. - Finger path depends on
SYSTEM_ALERT_WINDOWbeing granted to the
plugin host (com.ratta.supernote.pluginhost). On the tested
firmware it is granted at install time; other firmware revisions may
behave differently. - Finger tap delay of up to 1.5 s when switching pages/notes. The
Finger path uses a 1.5 s context poll to re-install
SYSTEM_ALERT_WINDOWoverlays after navigation, so a freshly
entered page can ignore finger taps for up to one poll interval.
Mitigation: replace the polling loop with an event-driven refresh
(e.g., subscribe to page/note change events from the SDK) so
overlays re-install immediately on navigation. - False activation risk on small deliberate strokes. The pen path
treats any stroke of ≤10 sample points as a tap (see
TAP_MAX_POINTS), so a very short intentional mark that lands
inside a saved rect can be consumed and trigger the shortcut. - Tool type detection assumes reliable
TOOL_TYPE_FINGERvs. stylus
classification. TheSYSTEM_ALERT_WINDOWoverlay only swallows
events wheregetToolType(0) == TOOL_TYPE_FINGERand passes
everything else through. Devices or firmware that misreport tool
type (e.g., stylus events arriving as finger, or vice-versa) will
either break writing over a linked word or stop finger taps from
opening the folder. - The shortcut's rect is anchored to the original lasso rectangle in
page coords. If a user erases or drastically rearranges the
underlying strokes, the sidecar entry will be stale. - Important: page coords are assumed 1:1 with screen pixels.
Verified only on a Supernote Manta. This assumption is fragile
across devices: other Supernote models (A5X, A6X, Nomad, future
revisions) may use different panel resolutions, DPIs, or zoom
levels, and the overlay rectangles will land in the wrong place on
screen. Action items for integrators: test on every target
Supernote model before relying on the plugin, and implement a
dynamic scale factor: derive it from device DPI / current zoom and
convert page coords to screen coords with that factor instead of
using the raw values.
Build
Prerequisites
- Node 18+
- Java 21 (Gradle 8.13 does not support Java 24+)
- Android SDK with build-tools installed
npm install
bash buildPlugin.shbuildPlugin.sh auto-selects Zulu 21 on macOS when the system java
is too new, and auto-sets ANDROID_HOME to
~/Library/Android/sdk if unset. The output is
build/outputs/SupernoteFolderShortcuts.snplg.
Install
Plugins must live in /MyStyle/ on the device storage. Copy
SupernoteFolderShortcuts.snplg to MyStyle/ via USB (or with adb push) and install it from the plugin manager on the device.
adb push build/outputs/SupernoteFolderShortcuts.snplg /sdcard/MyStyle/