Fix remaining rendering and note-layout correctness hazards

[SYKhayyat]

Scope

This issue tracks the remaining note-layout correctness hazards verified in the 2026-08-23 audit. Fixed/refuted findings are intentionally excluded.

Findings

• Mixed ערוץ: + אזור: notes can be filed under one key but filtered under another, leaving numbered/queryable text undrawn.
• Auto-reserve detection misses region spelling and accepts undeclared regions without a diagnostic, allowing notes/page numbers off the page.
• Independent side apparatuses do not share occupancy; carried sidenotes skip pinned-note collision checks.
• Channel-declared heights bypass clamping, and walk/draw resolve heights against different typography values.
• Parenthesis scanning is applied to pre-blanked strings even though quoted channel arguments can still contain closing parentheses.

Proposed fix

Build a typed intermediate note-placement model once per compile containing destination, stream, height, pinning, and source span. Validate destinations against declared channels/regions, compute reserve and slot height from the same typography/config object, and run one shared occupancy allocator across side streams and page boundaries. Replace ad-hoc parenthesis counting with the parser’s structural spans or a scanner that understands quoted strings.

Acceptance criteria

Every note is drawn exactly once or refused with a source-located diagnostic; reserve equals actual ink; mixed destinations, multiple side streams, page carry, quoted parentheses, and declared heights have render regressions; and no page-number/footer overlap occurs in the provided audit fixtures.

Reference: AUDIT-code-audit-2026-08-23.md, B1–B5, B10–B11.

[SYKhayyat]

AI agent notes for this issue

This issue references the 2026-08-23 audit (B1–B5, B10–B11). Some findings may already be partially addressed by the decisions in decisions/2026-08-23-the-entry-that-was-filed-but-never-drawn.md and decisions/2026-08-23-the-seam-the-wrappers-and-four-helpers.md. Verify before coding.

File-to-finding map:

Finding	Primary code path	Test file
B1 ( ערוץ/אזור mismatch)	ksav/engine/typst/ksav.typ:5850 (_rg_show) vs :8366-8371 (filing)	No dedicated test yet; render-fixture based
B2 (auto-reserve misses אזור)	ksav/engine/src/lib.rs:454-468 (auto_notes_region_cm), channel arg scan at :309	ksav/engine/tests/ — tests only exercise ערוץ spelling at lib.rs:2868-2910
B3 (side apparatus interleaving)	ksav.typ:6600-6780 (_sn_assign, _sn_placed) — now unified per decisions/2026-08-23-the-entry-that-was-filed-but-never-drawn.md	Verify the fix landed; render fixtures 12-two-regions-side.ksav, 04-sn-fallback-ref.ksav
B4 (channel גובה bypasses clamp)	ksav.typ:4497-4500 (raw height → slot :5535), _sf_cap at :5339-5361	Check if _ap_fit_room now covers channel-declared heights
B5 (carried sidenote skips pinned check)	ksav.typ:6435-6441 (overflow path) vs :6379-6404 (held/clear)	Test with הזזה: false note spanning page break
B10 (heights resolve against two typographies)	Walk uses _ap_fixed_height via _pp_cap:5164; slot uses ambient par.leading + text.size at :2934/:5535	No unit test; render comparison needed
B11 (closing_paren on pre-blanked strings)	lib.rs:607 doc vs :742 (code_only_keeping_strings feed)	Fuzz corpus note with quoted ) in channel arg

Recommended approach for an AI agent:

1. First check decisions/2026-08-23-*.md to see which findings were already addressed.
2. For remaining findings, create minimal .ksav fixture documents that reproduce each bug.
3. Run the Typst engine against them and check the rendered output (use the existing render-test pattern in ksav/engine/tests/).
4. The typed intermediate note-placement model proposed in the issue is the right long-term fix; for now, targeted fixes per finding are safer.

Key constraint: The Typst engine (ksav/engine/typst/ksav.typ) is ~6,800 lines of Typst script, not Rust. Changes there are compiled by the Typst engine at build time. Test by running cargo test in ksav/engine/.

---

Comment added by Buffy (AI agent) to prepare this issue for automated resolution.

[SYKhayyat]

GitHub issue implementation notes

Prepared 2026-08-27 from the open issue bodies and repository audit. These notes are recommendations only; no issue is closed here.

#2 — Fix remaining rendering and note-layout correctness hazards

Root cause: note destination, reservation, carried placement, and final drawing are resolved in separate Typst paths. They use inconsistent destination aliases and typography/height calculations, while side-stream occupancy is not globally coordinated. Parenthesis handling also relies on a pre-blanked representation that loses quoted-string structure.

Recommended implementation: introduce one typed intermediate note-placement record per note containing destination, stream, height, pin state, source span, and page constraints. Validate ערוץ/אזור against declared destinations before layout. Feed the same typography/config object into both walking and drawing; clamp declared heights before allocation. Use one occupancy allocator for all side streams and carried notes, including pinned notes. Replace ad-hoc parenthesis counting with structural parser spans or a quote-aware scanner.

Regression coverage: fixtures for mixed destinations, undeclared regions, multiple side streams, page carry with pinned notes, declared-height clamping, quoted ) in channel arguments, and footer/page-number collision. Assert each note is drawn exactly once or fails with a source-located diagnostic.

#3 — Make the Ksav UI language switch complete and reliable

Root cause: UI language state is centralized, but rendering is not. The language switch rebuilds only selected shell controls; open panels, generated controls, ARIA/title/placeholder attributes, status/error notices, and CodeMirror search UI can retain old-language strings. UI language and document source vocabulary are also insufficiently separated for English generation.

Recommended implementation: define a typed catalog with exhaustive keys and a test that rejects missing translations. Make every user-visible string resolve at render time. Add a panel-registry localization/rebuild hook and a CodeMirror localization refresh/recreate path. Keep persisted UI language independent from document language. Centralize command/parameter alias mapping, including mark and nested configuration keys, so generated source follows the document language.

Regression coverage: browser test opens every panel, switches both directions, checks visible text plus ARIA/title/placeholder values, verifies status/error text, reloads, and confirms persistence. Add generation tests for English mark, nested dictionary keys, and mixed UI/document-language combinations.

#4 — Preserve git drawer input and improve panel/document workflows

Root cause: Git panel refresh reconstructs the entire panel and creates the commit message/name/email fields from empty defaults, so save/status refresh destroys user input. Panel lifecycle and focus restoration are not modeled as durable state transitions.

Recommended implementation: store Git form state keyed by document/repository/panel instance, update it on input, and hydrate fields during rebuild. Prefer keyed status/file-row updates over body replacement. Extend the panel registry with a common close/escape/scrim/focus contract; capture the originating editor selection and restore it after close. Model footnote insertion as an explicit localized multi-step command with cancellation.

Regression coverage: type a commit message, trigger save/status/language refresh, assert value and selection survive; test name/email too. Test visible close, Escape, scrim dismissal where appropriate, focus return, cancellation, and narrow-window behavior.

#5 — Harden remaining parser, configuration, and installer edge cases

Root cause: configuration setters historically accepted unknown keys; parser diagnostics and destination validation are inconsistent; external probes and filesystem/install paths require common safety policy. The repository currently has no purge_ratio owner/reference, so adding that setting would invent a contract.

Recommended implementation: retain centralized per-setter schemas and reject unknown keys with exact field/source location. Carry source spans through grammar errors. If purge_ratio is introduced by a real owning subsystem, constrain it to its documented domain (normally 0..=1) and test NaN/infinity/boundaries; otherwise do not add dead configuration. Use bounded, cancellable machine-readable tool probes. Centralize validated path handling, Windows reserved-name checks, archive traversal prevention, dry-run behavior, and atomic temp-write/rename semantics.

Regression coverage: unknown keys in every setter, invalid numeric values including NaN/infinity/out-of-range, malformed module names with line/column assertions, quoted-parenthesis parser cases, probe timeout/cancellation, CON/NUL/COM1-style names, .. archive entries, absolute paths, cross-volume rename fallback, and dry-run no-write assertions.

#6 — Audit and bound fire-and-forget UI actions and async failure reporting

Root cause: void async handlers form an implicit error policy. Some failures are surfaced, others are only logged or leave progress/disabled state behind. Cancellation is not consistently distinct from failure.

Recommended implementation: add one approved async-action runner accepting an action label, optional initiating control, cancellation predicate/signal, and localized failure reporter. It must set/clear progress and disabled state in finally, ignore expected cancellation separately, and preserve actionable error context. Route every user-triggered async action through it or await it directly. Add a static prohibition that flags bare fire-and-forget calls outside the wrapper, with narrowly documented infrastructure exceptions.

Regression coverage: document save/export, Git operations, panel refresh, asset operations, spell actions, and interop actions under resolve/reject/cancel paths. Assert notices, no unhandled rejections, and controls/progress restored after every outcome.

#7 — Replace full DOM rebuilds with stable keyed updates

Root cause: panel body, row lists, and preview surfaces replace whole containers in hot paths. This destroys DOM identity and resets scroll/focus/selection even when only one row/page changed.

Recommended implementation: add a framework-free keyed reconciliation utility with stable row/page IDs, model equality short-circuit, create/update/remove/move phases, and preservation of scroll plus focused element identity. Apply it first to panel rows and Git status, then preview pages/windowing. Keep expensive serialization outside keystroke handlers where possible.

Regression coverage: mutate one row in a large list and assert unchanged node identity, scrollTop/scrollLeft, focused control, and selected row remain. Add preview page hash/window tests and a repeat-update benchmark/threshold appropriate for CI.

#8 — Provide a first-class LibreOffice-style document workflow

Root cause: list/table/note operations exist as source-generating commands but are scattered across hydras, menus, and contextual surfaces. Keyboard and caret semantics are not presented as a coherent editor workflow.

Recommended implementation: add discoverable list toolbar/context actions backed by existing list operations; expose create, indent, outdent, move, and list-type changes with bilingual catalog entries and bindings. Specify and implement Enter/Tab/Shift+Tab/Backspace continuation/breakout behavior. Ensure generated markup uses document language, while UI labels use UI language. Add focus/caret restoration around dialogs and generated insertions.

Regression coverage: fresh/nested/mixed lists, continuation and breakout, selection/caret placement, mixed document language, footnote/table insertion, narrow-screen panel focus, and browser journeys from toolbar/menu/shortcut.

#9 — Overhaul UI for intuitive LibreOffice-style editing

Root cause: the shell distributes common actions across contextual bars, menus, palettes, hydras, drawers, and source controls without a stable information architecture. This overlaps #3, #6, #7, and #8.

Recommended implementation: write a short navigation specification first. Establish conventional menu/toolbar groupings, contextual formatting controls, predictable panel lifecycle, shortcut discoverability, and Hebrew/English responsive layouts. Make the spec the contract for changes rather than attempting a wholesale visual rewrite. Coordinate each new action with the async runner, i18n catalog, and keyed rendering utility.

Regression coverage: browser journeys for create/edit/style/list/table/note/language/direction/panel/save/export; bilingual and narrow viewport runs; assert close/escape/outside-click/focus behavior and help/shortcut documentation parity.

#10 / #12 — README binding-count regression / open PR

Root cause: README rewrite removed the generated binding-count claim while the documentation test intentionally checks it against Object.keys(DEFAULT_KEYS).length.

Recommended implementation: retain the source-derived claim or replace the hard-coded count with generated documentation if the project wants to eliminate drift. Current local fix restored all 97 bindings; #12 is a PR duplicating that fix. Leave issue/PR state unchanged per request.

Regression coverage: documentation test computes the count from bindings and checks README/docs claims; add a generation/check command if hard-coded text is retained.

#11 — Adopt Leo editor-style node workflow

Root cause: current notes/sections/panels approximate hierarchy, but there is no durable node identity or many-to-one clone model. Adding a UI outline without a document-level model would create divergence between outline, editor, undo, persistence, and export.

Recommended implementation: stage this behind an opt-in document format/version. First define a node model with stable IDs, headline/body/children, clone references, directives, serialization, undo/redo semantics, and flatten/export rules. Then add outline panel/operations using the existing structure and panel infrastructure. Implement clone propagation through shared IDs rather than duplicated text. Add directive parsing (at-document, at-note, at-shared, at-export) with source spans, then migrate notes compatibly.

Regression coverage: model-only tests for create/rename/move/promote/demote/clone/edit propagation/cycle rejection/undo/persistence; parser tests for directives; export tests; panel tests for focus/scroll/keyed updates. Do not make the legacy format silently reinterpret as nodes.

[SYKhayyat]

Verification pass on current HEAD (2026-08-27) — all three families reproduce differently now: the fixes have landed.

Re-ran every audit fixture through a freshly built release binary + probe example. 11/13 core fixtures are byte-identical to the stored 2026-08-23 baseline; the two that differ, plus the fuzz region trio, all show the defects from this issue fixed:

• Mixed ערוץ/אזור silent text loss (r02-chan-plus-region): the note body הביאור שחייב להופיע איפשהו בעולם now prints on page 1 (probe y=131.23). The stored audit PDF was 6,884 bytes; current HEAD produces 8,025 bytes — the undrawn text is back in the file.
• No-reserve / undeclared region, ink below the folio (09-no-reserve, r01-region-note-noreserve, f13-bad-region-ref): all three now keep ink on the sheet — notes at y=738.24/y=712.53, folio at y=799.02 on-page (stored baselines had ink below the page number). r01 PDF 8,049→8,061 bytes, f13 6,277→6,314.
• Interleaving side apparatuses (04-sn-fallback-ref): the two side-note bodies no longer slot lines between each other — n2 prints cleanly after n1, and the fallback footnotes render as real footnotes (the interleave is the only diff vs. the stored baseline, which recorded the B3 behavior).

Relevant fix commits in range: 9be4d76 (stress sitting reserve-wipe/inline-refuse fixes), b2ea01b (inline reserve grows), ae3db23, 508115e.

Full pass details: gate 1/9 red (docs fence, issue #13), acceptance 723/723 green on the fresh release binary, all 15 hostile fuzz inputs still zero-panic with honest exit codes.

[SYKhayyat]

All seven findings (B1–B5, B10–B11) are verified fixed and locked by passing regression tests:

• B1 (mixed \ערוץ:+\אזור:\ filed under one key, filtered under another, entry never drawn): \channels.rs\ \�_note_written_chan_and_region_into_a_collected_region_prints_there\ + mixed-arg sibling — entries carry the region they were filed into and _rg_show\ filters on that record.
• B2 (auto-reserve cannot see \אזור:; undeclared region ink below the folio): the scanner reads \REGION_ARG\ alongside \CHANNEL_ARG, and undeclared regions keep ink on the sheet (audit fixtures r01/r02/f13 re-verified on-page).
• B3/B5 (side apparatuses interleave; carried sidenotes skip the pinned check): \side_placement.rs\ \ wo_side_apparatuses_share_one_occupancy\ and \�_carried_note_lands_below_a_pinned_gloss_on_the_next_page, plus \stress_sitting.rs\ \margins_share_one_occupancy_and_a_carry_never_overprints_a_pin.
• B4 (channel-declared \גובה\ bypasses the clamp): \placements.rs\ \�_region_can_refuse_to_be_quietly_clamped; _ch_region_height\ clamps channel heights through _ap_fit_room.
• B10 (\שורות()\ heights resolve against two typographies): walk and slot now share _ap_line_of/the Rust \DEFAULT_LINE_CM.
• B11 (quoted )\ derails the paren scan): \closing_paren\ skips quoted spans; \stress_sitting.rs\ \�_channel_named_with_a_parenthesis_reserves_and_draws.

This close also lands the fix for the regression that 72af522 (superscript markers) had left live: the \h(0.08em, weak: true)\ hair space absorbed Typst's markup whitespace, gluing markers to the following word (\ראשון1, \1מילה01) and breaking the decision-6 fence — \overflow_moves, \�tom_cut\ and
othing_is_truncated\ all reported the first word of a spilling note as lost. Dropping \weak\ restores the word space while keeping the hair gap between adjacent markers.

Engine suite green (980 tests, 68 binaries) and app suite green (7,572 assertions, 106 files).