notes-browser Development TODOs

Design Ideas

Control socket goes unresponsive under concurrent / second-session use — 2026-08-05. The JSON-RPC control server (Unix socket, e.g. /home/john/tmp/notes-browser-private.sock) stops answering when driven from more than one client/session. Observed: a stuck nc -U navigate.go_to_page request from one session left the socket jammed, so a second client's status.capabilities timed out — the browser process stays alive but the control server never replies, and it doesn't recover without a full restart. Likely single-threaded/serialised handling on the wx UI thread, where one blocked, slow, or half-open request stalls every subsequent connection (related to UI freezes while cell running above). Investigate the accept/dispatch loop: service each connection concurrently (worker thread/queue), never run RPC work synchronously on the UI thread, add per-request timeouts, and clean up half-open connections so a wedged client can't lock everyone out. Repro: open the socket from one session and don't complete a request, then issue any RPC from another.

Review bottom-of-window status messages — Check the messages shown in the Notes Browser status bar during navigation, loading, saving, errors and control-socket actions. Confirm that each message is useful, understandable, timely and accurately describes the current state; remove stale, noisy or misleading messages and make desktop/runnable behaviour consistent.

Snapshot a runnable note's output as a non-runnable note — 2026-07-10, confirmed still unimplemented 2026-07-13, built 2026-07-17 as "Fix as New Note…". See notes-browser/fixed-notes for the full design, and the "Completed" entry below for what's still open (desktop-side details collapsing needs a bigger architecture change, not done).

Scrolling to cell image output via the control API is unreliable — 2026-07-13, while iterating on location/speed-plot's label layout. sheet.cell.run with scroll:true and sheet.cell.scroll_into_view both exist and don't error, but neither reliably brought a cell's rendered show(fig) image into a screenshot — they seem to target the cell's code/top rather than its output. Worse, calling ui.set_window_size with a much larger height after a successful scroll-to-cell reliably reset the scroll position back to the top, so the usual "make the window huge, screenshot once" trick only worked intermittently. Also confirmed sheet.get_state (include_outputs=true) returns only text output per cell, not show_items — so there's currently no API path to pull a rendered image back out without a correctly-scrolled screenshot (see the related gap logged under "Snapshot a runnable note's output" above). Workaround that did work: resize the window tall, then re-run the specific cell with scroll:true before any further resize, and screenshot immediately — but this was trial-and-error, not something to rely on for unattended automation.

Render links in JSONHTL table cells consistently — 2026-07-30. Spec settled 2026-07-30 (README/format, JSONHTL_SCHEMA, gdata-server/linter): a table cell may be a string or an inline-element list (same content model as para), so a link is expressed as a structured [{"link": {"href": ..., "text": ...}}] cell — the same object used in a paragraph, not Markdown [text](target). Renderer work remaining: both renderers must render inline-element-list cells by reusing their existing per-inline renderers — notes-browser/notes_browser.py (NotesHTMLRenderer._render_table, feed each cell through the same inline path as _render_markup_text) and notes_web.py (_render_block table path, feed each cell through the same inline renderer as _md_inline). Internal link targets use the Notes Browser navigate:// path and web /notes/<key> path; external http(s) links stay restricted to safe handling. Plain-string cells keep rendering exactly as now; preserve HTML escaping and existing bold/code/italic. Add desktop coverage to notes-browser/test_render_inline_table_read.py and web coverage to test_notes_web_table.py: string cell, inline-list cell with internal link, external link, escaped link text/target, and a mixed row. Then convert the jira/tickets table (private store) to inline-link cells and confirm it is clickable in both the desktop UI and HTML renderer before removing its temporary structured-link section.

Documentation

Interactive checkboxes on list items — List block items that have a status field ("open"/"done") should render as tickable checkboxes in the browser UI. Clicking should toggle the status and persist via the notes API. Useful for todo/tracking notes where either the user or Claude can mark items complete.

Completed (pending browser restart)

Desktop app can't actually collapse <details> blocks — 2026-07-17, while building "Fix as New Note" (see notes-browser/fixed-notes). wx.html.HtmlWindow has no <details>/<summary> support at all — confirmed empirically it just renders the "hidden" content as permanently visible text. Degraded to always-expanded (in a bordered box) rather than block on it. A real fix needs a native wx.CollapsiblePane widget per details block, which needs the desktop note-viewing architecture to change from one HTML blob per page (NotesHTMLRenderer.render() builds a single string, set once via SetPage()) to a sizer of mixed HTML-panel and native-widget children — the same class of change svg/image blocks avoided needing by staying image-based (embeddable inline via <img src="memory:...">), but a collapsible pane can't be embedded inside an HTML string at all. Affects every note view in the desktop app, not just fixed notes, so this is a bigger, separate piece of work — not attempted here.

✓ Cell status label centring — added second stretch spacer in sheet_ui.py so the status text is centred between cell name and Run button. In git (2026-05-29); takes effect on next browser restart.

2026-06-05: Added File > Save Sheet menu item (Ctrl+S), enabled only when a runnable sheet is loaded. Fixed cell name label contrast (dark foreground colour on light header).

Cell output scroll control via API — Cell output panels have a scrollbar but there is no control socket method to scroll them. Add a sheet.cell.scroll_output method that accepts a cell ref and a position (e.g. "top", "bottom", or a pixel offset) so that API callers can bring a specific part of a cell's output into view.

Control-enabled notes_browser.py lacks sheet RPC methods — 2026-07-10 while creating the runnable sheet movement, the browser API successfully handled page.put_document_json and navigation, but status.capabilities from notes_browser.py did not include sheet.* methods and sheet.get_state returned method not found. For runnable-sheet automation, start notes_browser_runnable.py or merge/register the sheet RPC methods into the main browser entry point so the documented control API matches the launched UI.

Screenshot APIs can report zero client size after successful resize — 2026-07-10 while inspecting the runnable sheet movement, ui.set_window_size(1280,900) returned a non-zero frame size, and sheet.cell.scroll_into_view succeeded, but both ui.capture_screenshot and ui.capture_sixel failed with Window has invalid size for screenshot from _capture_window_bitmap() because GetClientSize() was zero. Need to investigate minimized/unmapped-frame handling and make capture either restore/show the frame before capture or report enough window state for callers to remediate.

HtmlOutput SVG is not rendered by wx.html output panels — 2026-07-10 while inspecting movement via ui.capture_screenshot after fixing screenshot capture, an inline show(HtmlOutput(...)) SVG bar chart appeared as text rather than rendered graphics. Workaround used in the sheet: generate a plain HTML table-based bar chart. Longer-term options: document supported HTML subset, add explicit image/bitmap output support, or render richer HTML through a browser component rather than wx.html.HtmlWindow.

selection.read_text reports inconsistent selection metadata — 2026-08-03. The control-socket method returned the highlighted/current line correctly, but reported selection_mode: "none". The text result remains usable, so this does not block automation; correct the mode metadata so it accurately describes how the returned text was obtained.

✓ 2026-08-04: Render links in JSONHTL table cells — DONE. Both renderers now treat a table cell as a string or an inline-element list and route it through their existing inline renderer: notes_web.py _render_cell() (web, /notes/<key>) and notes_browser.py _render_cell() (desktop, navigate://). Web deployed live to gravlax; desktop in git (commits 92e0545, 59213ad), takes effect on browser restart (the running private browser was restarted and shows it). jira/tickets (private) converted to inline-link cells and verified clickable in both renderers. Tests: +6 test_notes_web_table.py, +6 notes-browser/test_render_inline_table_read.py. Spec settled in README/format, JSONHTL_SCHEMA, gdata-server/linter.

version 9  ·  updated 2026-08-05