rails-markup risk register
Audit notes for usability and JavaScript collision risk after release 1.4.7.
status: active · version 1.4.7 · source: nauman/rails-markup
Summary
The gem is in good shape for normal Rails engine use. The main risks are not feature correctness; they are discoverability, future UI density, and collision hygiene if host apps use aggressive global JS/CSS.
Risks
| Risk | Current status | Impact | Mitigation |
|---|---|---|---|
| Settings discoverability | Addressed in 1.4.7 | Low | Settings gear is always visible in the toolbar cluster. Keep it there. |
| Toolbar density | Acceptable now | Medium if more controls are added | Group future settings into sections instead of adding another flat row of chips. |
| FAB / panel confusion | Reduced | Low | Keep FAB dedicated to annotation mode and panel toggle dedicated to review. Do not restore auto-open behavior. |
| Global event listeners | Accepted design tradeoff | Medium | Keep teardown paths strict and test Turbo/visibility/scroll cleanup on every toolbar edit. |
| Host CSS collisions | Low | Medium in hostile host apps | Keep all toolbar DOM, classes, and IDs namespaced under rm-* and #rm-toolbar-root. Avoid unscoped selectors. |
| Host JS collisions | Low | Medium in hostile host apps | Continue avoiding native selects and browser-default UI controls that host frameworks rewrite. |
| LocalStorage namespace drift | Low | Medium across multi-app hosts | Keep annotation state and toolbar settings endpoint-scoped. Never collapse them into a shared key. |
| Duplicate mounting | Low | Medium | Preserve the singleton guard so repeated Turbo visits or duplicate partials do not create stacked toolbars. |
| Mount-path misunderstanding | Low | Low | Default now points at /admin/rails-markup; document overrides clearly when a host prefers /dashboard/rails-markup or another scoped path. |
What to watch next
- Re-run the JS state tests whenever toolbar markup, listeners, or settings are changed.
- Re-check mobile spacing if the settings panel gains more sections.
- Keep the public docs and the generator defaults in sync whenever mount-path behavior changes.
source: nauman/rails-markup · audit note
Addendum
The mount-path risk is now mostly a documentation concern, not a behavior concern: the installer prompts for a nested prefix when --mount-path is omitted, and explicit paths still work for hosts that prefer /admin/rails-markup or /dashboard/rails-markup.