gitoria

6.4 KB

1. # Differ from custom-ide — reuse assessment
3. Research for ticket [gitoria.worldapi.org#2](https://tickets.worldapi.org/projects/gitoria.worldapi.org/2).
4. Source inspected: `loreana:/media/STORAGE/projects/custom-ide` (renderer, vanilla JS + vendored
5. CodeJar, no framework), specifically `renderer/src/features/{editor,diff-review,hybriel}` and
6. `docs/editor-split-and-diff.md` (the design log for the diff feature, approved 2026-07-30).
8. ## What the "differ" actually is
10. Not one file — five pieces, ~3,400 LOC total, built up over several phases (see the design log):
12. | Piece | File | LOC | DOM? |
13. |---|---|---|---|
14. | Diff algorithm | `editor/lineDiff.js` | 249 | **No** — pure, aligns two texts into rows (patience-diff anchors + LCS fallback, `MAX_LCS_CELLS` guard) |
15. | Live gutter bars | `editor/editorChangeBars.js` | 75 | No — reuses `lineDiff` |
16. | Diff widget shell | `diff-review/DiffReviewWidget.js` | 302 | Yes — two `EditorSurface`s side by side |
17. | Editor surface (gutter, spacers, highlight, scroll) | `editor/EditorSurface.js` | 614 | Yes, heavily |
18. | Canvas minimap | `editor/EditorMinimap.js` | 628 | Yes (canvas) |
19. | Syntax highlighters (per language, regex-based) | `editor/editorHighlighter.js` | 1,027 | No |
20. | Vendored editing library | `vendor/codejar.js` (npm `[email protected]`, MIT) | 499 | Yes |
22. `EditorWidget.js` itself (2,770 LOC) is mostly file/LSP/dirty-tracking plumbing the differ doesn't
23. need — excluded above.
25. ## Reusability, piece by piece
27. **`lineDiff.js` — yes, directly.** Zero DOM dependency (the code comments say so explicitly: kept
28. separate *because* importing it into the widget would have dragged in CodeJar, which needs a
29. `window`). It has its own Node smoke test. This is the actual "differ" and is the easiest, highest-value
30. piece to make a shared component: a worldapi-wide `differ` module, callable from any project
31. (gitoria diffs, but also e.g. a future review UI), with no browser coupling at all.
33. **`editorHighlighter.js` — yes, and partly done already.** custom-ide already ships a **Hybriel
34. syntax highlighter** at `renderer/src/features/hybriel/highlight.js` (regex tokenizer over
35. Hybriel's keyword/type/operator set, ~70 LOC, no dependencies) — written for its own use, but
36. directly reusable verbatim for `.hl` files in gitoria's diff/editor views.
38. **CodeJar + `EditorSurface` + `EditorMinimap` — a large piece (not "easily rewritable") — to be ported natively.**
39. This is where the ticket's premise ("codejar is quite simple and probably easily rewritable in
40. hybriel") undersells the actual scope. CodeJar itself is small (499 LOC, MIT, plain
41. `contenteditable` + `Range` API) and easy to read. But the feature built on top of it is not simple:
42. the design log documents real trial-and-error to get there —
43. - diff alignment uses `contenteditable="false"` DOM "spacer" elements inserted via `Range` (not
44. blank text lines), so the editable side's `getCode()` stays byte-identical to the real file;
45. - spacers must be re-inserted after **every** re-highlight because CodeJar rewrites `innerHTML`
46. each time, or the two sides drift a line apart;
47. - line-highlight bands are positioned from `getComputedStyle` line-height, deferred via
48. `ResizeObserver` because a detached element reports no real metrics;
49. - the minimap is a hand-rolled canvas renderer with its own tokenizer-output reuse, viewport slider,
50. and marker ruler.
52. None of that complexity is intrinsic to codejar — it's what "diff editor with a minimap, gutter,
53. and an editable proposal side" costs regardless of implementation language.
55. ## Would a native Hybriel rewrite work today?
57. Judged against the open Hybriel tickets already known to this project (see the worker brief's list),
58. several are direct blockers for exactly this feature, not incidental:
60. - **hybriel#32** (`hl:webex` re-creates elements, incl. `script src`, when an `if` in the same View
61. flips) — the diff widget's "changed only" toggle and the read-only/editable swap are precisely
62. this pattern: conditional re-render of a live editing surface, which would blow away CodeJar's
63. DOM/caret state on every toggle if View re-creates the node.
64. - **hybriel#33** (no conditional boolean attributes) — `contenteditable`/`aria-readonly` are
65. boolean-attribute toggles core to `EditorSurface.setReadOnly()`.
66. - **hybriel#31** (no custom DOM event binding) — CodeJar communicates through its own `onUpdate`
67. callback and native `input`/`keydown` handling, not a framework event system; a native port needs
68. a way to hand webex an escape hatch into the raw DOM.
69. - **hybriel#17** (`if (!member)` renders nothing) and **hybriel#9** (manifest statics unreadable in
70. their own function routes) are the kind of "silent wrong render" bugs that are expensive to debug
71. inside something this DOM-fiddly.
73. None of these make a Hybriel differ *impossible* — but they make a **from-scratch native rewrite of
74. the editing surface** premature until webex's conditional-rendering and DOM-event story is solid.
75. The diff *algorithm* has no such dependency and is unaffected.
77. ## Recommendation (final, after gitoria#4)
79. The creator rejected the JS-asset route: no foreign bundle is embedded. The plan is native Hybriel only:
81. 1. **Differ algorithm first** — port `lineDiff.js` (pure, 249 LOC, no DOM) as a native Hybriel module in
82. layouts.worldapi.org (shared components live there, gitoria#3). Unblocked; needs a ticket in that project.
83. 2. **Editing surface** — build natively (spacers, re-highlight, contenteditable toggling, custom DOM
84. events). Blocked on hybriel#31/#32/#33/#17 (and #41); fix or work around those in Hybriel itself.
85. The custom-ide code stays a reference for the behaviours to reproduce.
87. (An earlier "tier 1: ship the existing JS as a client asset" recommendation was removed; it is rejected.)
89. ## Questions
91. - ~~Where should the `differ` module live?~~ Decided by the creator (gitoria#3): shared components
92. (editor, differ, comments, design tokens) live in **layouts.worldapi.org**, not in gitoria and not
93. in a separate project.
94. - ~~Embed custom-ide's CodeJar bundle as a static JS asset for now?~~ **Rejected by the creator
95. (gitoria#4):** the original ticket (#2) already answered it — editor and differ are to be built as
96. reusable **native Hybriel components** in layouts.worldapi.org, not embedded as a foreign JS bundle.
97. Do not build the JS-asset route.
98. Remaining work is the native port (differ algorithm first — unblocked; editing surface — see the
99. open Hybriel tickets #31/#32/#33/#17 above, which must be fixed or worked around in Hybriel itself).