# Developer Knowledgebase A reference for developer onboarding and technical context for developers wanting to customize or expand the Traven WYSIWYM Markdown Editor. --- ## 1. Repository Architecture & Layout Traven is designed to be a lightweight, framework-agnostic editor component. It is compiled to standard ES Modules (ESM) with zero runtime peer-dependencies: * **[package.json](../../package.json)**: Bundler settings (`esbuild`), script pipelines (`npm run build`/`watch`), and versioned CodeMirror 6 packages. * **[packages/core/src/index.js](../../packages/core/src/index.js)**: Public API surface exposed via the `TravenEditor` class (mounts CodeMirror, encapsulates state lifecycle, inserts snippets, and fires events). * **[packages/core/assets/skins/](../../packages/core/assets/skins/)**: Decoupled stylesheets (`skin-starter.css`, `skin-light.css`, `skin-colorful.css`, `skin-dark.css`, `skin-editorial.css`, `skin-modern.css`, `skin-academic.css`, `skin-custom.css`) containing editor visual theme configurations that require no rebuilds. * **[packages/core/assets/toolbars/toolbar-default.css](../../packages/core/assets/toolbars/toolbar-default.css)**: Decoupled toolbar presentation stylesheet, letting users skin and toggle toolbar buttons independently. * **[packages/core/src/toolbar/](../../packages/core/src/toolbar/)**: Modular toolbar components (`toolbar.js`, `tools.js`, `modal.js`) handling dynamic generation, accessibility behaviors, modals, and actions. * **[packages/core/src/wysiwym.js](../../packages/core/src/wysiwym.js)**: Core decoration state machine mapping markdown parser nodes to collapsed replacement decorations. * **[packages/core/src/delimiter-skip.js](../../packages/core/src/delimiter-skip.js)**: Arrow-key keyboard hook checking if cursors are on boundaries of folded syntax blocks to skip them. * **[packages/core/src/images.js](../../packages/core/src/images.js)**: Drag-and-drop/paste optimistic file uploader mapping state adjustments. --- ## 2. Core Technical Findings & CodeMirror 6 Pitfalls During initial visual scaffolding and integration, we resolved several critical constraints inherent to CodeMirror 6's layout engine. Maintain these practices for any future styling or behavior modifications: ### A. Block Decorations inside ViewPlugins (RangeError) * **Problem:** In CodeMirror 6, block-level replacement decorations (e.g. `Decoration.replace({ widget: ..., block: true })` or custom line widgets) cannot be returned directly from the `decorations` facet of a standard `ViewPlugin`. Attempting to do so triggers a `RangeError: Block decorations may not be specified via plugins`. * **Fix:** The decorations must be defined using a `StateField` and exposed to the editor view via the state field provider `provide: (field) => EditorView.decorations.from(field)`. Both `wysiwym.js` and `images.js` use this pattern. ### B. Accurate Click Targeting & Character Width Caching When hiding elements or editing syntax markers (like `**` or `_`), CodeMirror must know their rendered widths to map cursor clicks to correct character offsets. * **Avoid CSS-based Hiding:** Do not collapse character widths using CSS (`font-size: 0`, `width: 0`, or `opacity: 0` on standard `Decoration.mark` elements). CodeMirror's coordinate mapping engine remains unaware of the collapsed size, making mouse clicks land offset from their visual target. * **Use Native Replacements:** Use `Decoration.replace({})` to collapse syntax ranges. This natively informs CodeMirror's layout engine that the text range is replaced with an empty 0-width fragment. * **Defer to Font Loading:** CodeMirror measures and caches character widths on initialization. If fonts (like Google Fonts) load asynchronously *after* the editor renders, the width cache becomes invalid, causing cursor misalignment. Always initialize the editor inside a `document.fonts.ready.then(...)` block: ```javascript document.fonts.ready.then(() => { new TravenEditor({ ... }); }); ``` ### C. Layout Measuring & Vertical Margins (Vertical Offsets) * **Problem:** Standard line elements in CodeMirror (`.cm-line` or line decorations) must be stacked sequentially. Applying vertical margins (`margin-top` / `margin-bottom`) to headings or blockquotes pushes lines apart in a way that CodeMirror's layout calculations do not measure, causing mouse clicks to land on the wrong lines entirely. * **Fix:** Never use vertical margins on line elements or inline widgets. Always use vertical paddings (`padding-top`/`padding-bottom`) to create vertical layout spacing: ```css .cm-wysiwym-h1 { padding-top: 24px !important; padding-bottom: 12px !important; margin: 0 !important; } ``` ### D. RangeSetBuilder Sorting Constraint (startSide) * **Problem:** `RangeSetBuilder.add` requires that all ranges added are strictly ordered by `from` position ascending. If two ranges share the same `from` position, they must be added in order of their decoration's `startSide` ascending. Failing to do this triggers: `Error: Ranges must be added sorted by from position and startSide`. * **Fix:** When sorting decorations before building, use a multi-tiered comparator that compares `from` first, then `deco.startSide` (defaulting to 0 if not present), and finally `to` descending (larger range first). ### E. Custom Lezer Inline Parsers (Delimiter Resolution) * **API Pattern**: To implement custom inline formatting or shortcode wrappers (like `==highlight==`), utilize Lezer's `cx.addDelimiter` API rather than manually scanning/splitting strings. * **Automatic Balancing**: Register a delimiter object (e.g., `{ resolve: "Highlight", mark: "HighlightMark" }`). Lezer's engine will automatically match opening/closing boundaries, parse inner content recursively, and wrap the matched region in the `resolve` node type. * **Boundary Guards**: Always check for consecutive characters to avoid false matches (e.g. check `cx.char(pos + 2) == 61` to avoid parsing `===` as highlight delimiter `==`). * **Flanking Rules**: For delimiter activation to behave predictably at word boundaries and punctuation, implement flanking validation (checking if the characters immediately preceding and succeeding the delimiter match whitespace or Unicode punctuation). * **Styling**: Maps resolved node names (`HighlightMark`, `Highlight/...`) to Lezer's `tags` inside the parser config props using `styleTags`, or use high-level custom CSS classes inside the decoration builder pipeline in `wysiwym.js`. ### F. Lost Focus & Stale WYSIWYM Decorations (Measure Cycle Nudge) * **Problem:** In CodeMirror 6, view measurements and decoration-rendering cycles are driven by DOM events and the browser's paint loop. When a modal opens, it traps focus and moves it out of the CodeMirror editor. When closed, focus is returned to the `triggerElement` (the toolbar button) rather than the editor itself. In aggressive browsers (especially Firefox, which pauses `requestAnimationFrame` loops when focus moves outside the active DOM subtree), the editor remains in a stale state where WYSIWYM decorations disappear and raw Markdown is displayed until the user clicks inside the editor to trigger a new `mousedown` event. * **Fix:** When closing any modal or overlay that took focus away from the editor, perform a "nudge" to force CodeMirror to re-run its layout measure and decoration cycle. This is done by registering an `onClose` callback in the modal options, and calling `view.requestMeasure()` on the active CodeMirror view instance: ```javascript openModal({ title: "Insert Image", body: form, triggerElement: triggerBtn, onClose: () => { const view = editor.getView(); if (view && typeof view.requestMeasure === "function") { view.requestMeasure(); } }, buttons: [ ... ] }); ``` --- ## 3. Sandboxed Resizing Rules To prevent layout constraints on flexible split-screen dashboards: * Apply vertical resizability directly to the outer container card (`resize: vertical; overflow: hidden;`). * Configure the CodeMirror mount and editor container to scale proportionally to fill the card: ```css .editor-mount { flex: 1; overflow: hidden; } .editor-mount .cm-editor { height: 100%; } ``` --- ## 4. Toolbar Configuration & Button Customization Traven features a modular, dynamic toolbar system. Instead of hardcoded HTML markup, the toolbar is programmatically constructed by `buildToolbar` based on a configuration array passed to the `TravenEditor` constructor. ### Default Toolbar Layout By default, Traven displays the following tools in order (separated by pipe `|` characters for vertical dividers): * `undo` / `redo` (History controls) * `bold` / `italic` / `strikethrough` / `highlight` / `code` / `codeblock` (Inline formatting) * `heading` (H1–H6 selection dropdown) * `bulletlist` / `numberedlist` / `tasklist` / `blockquote` / `hr` / `table` / `component` / `figure` (Block and special elements) * `datetime` / `search` / `link` / `image` / `video` / `audio` / `fullscreen` / `clear` / `uppercase` / `lowercase` / `capitalize` / `removeformatting` / `gotoline` / `help` (Utility functions) This corresponds to the `DEFAULT_TOOLBAR` array defined in `src/index.js`. ### Customizing the Toolbar Layout To customize the order of buttons or hide specific ones, pass an array of tool keys to the `toolbar` property of the `TravenEditor` options during initialization: ```javascript new TravenEditor({ element: document.getElementById("editor-container"), initialValue: "# Hello World", toolbar: ["undo", "redo", "|", "bold", "italic", "link"] }); ``` To completely disable the toolbar, pass `toolbar: false`. ### List of Available Toolbar Buttons & CSS Identifiers Each button generated in the toolbar is assigned the class `.toolbar-btn` and a unique identifier class corresponding to its tool key (e.g. `.btn-bold`). These can be targeted for custom styling or hiding. | Tool Key | CSS Selector | Action Description | Default Keyboard Shortcut | | :--- | :--- | :--- | :--- | | `undo` | `.btn-undo` | Undo last operation | `Ctrl+Z` (`Cmd+Z` on Mac) | | `redo` | `.btn-redo` | Redo last undone operation | `Ctrl+Y` (`Cmd+Y` on Mac) | | `bold` | `.btn-bold` | Bold text (`**bold text**`) | `Ctrl+B` (`Cmd+B` on Mac) | | `italic` | `.btn-italic` | Italic text (`*italic text*`) | `Ctrl+I` (`Cmd+I` on Mac) | | `strikethrough` | `.btn-strikethrough` | Strikethrough text (`~~strikethrough~~`) | `Ctrl+Shift+S` (`Cmd+Shift+S` on Mac) | | `highlight` | `.btn-highlight` | Highlight text (`==highlight==`) | - | | `code` | `.btn-code` | Inline code backticks (`` `code` ``) | - | | `heading` | `.btn-heading` | Dropdown menu for Heading 1 to Heading 6 | - | | `bulletlist` | `.btn-bulletlist` | Unordered list formatting (`- `) | - | | `numberedlist` | `.btn-numberedlist` | Ordered list formatting (`1. `) | - | | `tasklist` | `.btn-tasklist` | Checklist formatting (`- [ ] `) | `Ctrl+Shift+C` (`Cmd+Shift+C` on Mac) | | `blockquote` | `.btn-blockquote` | Blockquote formatting (`> `) | - | | `hr` | `.btn-hr` | Horizontal rule line (`---`) | - | | `codeblock` | `.btn-codeblock` | Fenced code block (`` ``` ``) | - | | `table` | `.btn-table` | Insert table template via modal grid | - | | `datetime` | `.btn-datetime` | Insert current Date & Time | - | | `search` | `.btn-search` | Open CodeMirror search panel | `Ctrl+F` (`Cmd+F` on Mac) | | `fullscreen` | `.btn-fullscreen` | Toggle editor fullscreen mode | - | | `clear` | `.btn-clear` | Clear all document contents | - | | `uppercase` | `.btn-uppercase` | Convert selection to UPPERCASE | - | | `lowercase` | `.btn-lowercase` | Convert selection to lowercase | - | | `capitalize` | `.btn-capitalize` | Capitalize selection words | - | | `removeformatting` | `.btn-removeformatting` | Remove all markdown formatting styles | - | | `gotoline` | `.btn-gotoline` | Navigate to specific line | `Ctrl+G` (`Cmd+G` on Mac) | | `link` | `.btn-link` | Insert link using link modal dialog | `Ctrl+K` (`Cmd+K` on Mac) | | `image` | `.btn-image` | Insert image via URL or file upload modal | - | | `video` | `.btn-video` | Insert video shortcode via modal | - | | `audio` | `.btn-audio` | Insert audio shortcode via modal | - | | `component` | `.btn-component` | Insert `[component]` shortcode block via modal | - | | `figure` | `.btn-figure` | Insert `[figure]` shortcode block via modal | - | | `help` | `.btn-help` | Open keyboard shortcuts help modal | `Ctrl+/` (`Cmd+/` on Mac) | ### Hiding Buttons via CSS Although the preferred way to hide buttons is through the `toolbar` array configuration, host platforms can also hide toolbar buttons by editing or overriding styles in `packages/core/assets/toolbars/toolbar-default.css`. E.g., to hide the "Redo" and "Heading" buttons: ```css .toolbar-btn.btn-redo, .toolbar-btn.btn-heading { display: none; } ``` ### Adding a New Toolbar Button To add a brand-new formatting tool to Traven, follow these three steps: 1. **Register the Tool**: Define the tool metadata and action inside `src/toolbar/tools.js` under `TOOL_REGISTRY`: ```javascript strikethrough: { key: "strikethrough", title: "Strikethrough", shortcut: "Ctrl+Shift+S", keybinding: "Mod-Shift-s", icon: `...`, action: (editor) => editor.insertSnippet("~~", "~~", "strikethrough") } ``` 2. **Add to Toolbar Config**: Add the new tool key (e.g., `"strikethrough"`) to `DEFAULT_TOOLBAR` in `src/index.js`, or include it in the custom `toolbar` array passed during initialization. 3. **Optional Custom Styling**: Add specific visual rules for the button class (e.g., `.btn-strikethrough`) in `packages/core/assets/toolbars/toolbar-default.css` if custom styling is needed. --- ## 5. Runtime APIs, Extensions & Integration Hooks Recent core enhancements introduced runtime-level configurations, real-time analytics, custom markdown compilers, and Vim emulation. ### A. Editor Dark Mode Theme Traven supports a separate dark mode state for CodeMirror editor scopes, decoupled from the surrounding page context: * **Activation**: Set the initialization option `theme: "dark"` or call `setTheme("dark")` dynamically at runtime. * **Mechanism**: Dynamic theme toggling works by adding/removing the `.cm-wysiwym-dark` class from the editor host DOM nodes (`this.#view.dom` and `this.#rawView.dom`). * **Styling**: Specific dark styles (such as caret, gutters, code blocks, and markdown token colors) are separated into `src/style.css`. External visual skin styles are placed in scoped `.cm-wysiwym-dark` selectors in the respective skin files (e.g. `skin-light.css`, `skin-colorful.css`). ### B. Real-Time Statistics API Host applications can query document size statistics at runtime or subscribe to changes: * **Getter Methods**: `getCharacterCount()`, `getWordCount()`, and `getReadTime()` (calculates reading time dynamically using a standard 200 words-per-minute threshold). * **Event Hook**: Bind change listeners via `on("statsUpdate", (stats) => { ... })`. * **Important Timing Caveat**: When the editor is initialized, it fires the initial stats count. To guarantee that the host application has time to register its event listener, this initial trigger is deferred using a microtask: ```javascript Promise.resolve().then(() => { this.#triggerStatsUpdate(); }); ``` ### C. Dynamic Markdown Renderer Hook Traven features a compilation hook allowing custom renderers to generate the HTML preview: * **Registration**: Call `registerRenderer(renderFn)` to pass a custom Markdown-to-HTML parser function (e.g., marked, markdown-it, micromark). * **Usage**: `getContentHtml()` retrieves the rendered HTML of the current document. * **Out-of-the-Box Fallback**: If no renderer is registered, Traven falls back to `#fallbackRender(md)`, a secure, parser-assisted inline renderer that strips frontmatter metadata (via Lezer syntax tree boundaries) and parses headings, blockquotes, code, lists, linebreaks, images (`![alt](url)`), links (`[text](url)`), and inline text styling safely. * **Preview Styling & Skin Sync**: The preview container element uses the `.traven-preview` class. Styles for headings, lists, links, blockquotes, and code elements inside `.traven-preview` are defined directly in the theme skins (e.g. `skin-light.css`, `skin-colorful.css`, `skin-dark.css`) and dark mode class triggers (`.cm-wysiwym-dark`). This ensures the Preview tab mirrors the exact visual typography, colors, and borders of the current active skin and dark/light configuration dynamically. ### D. Vim Keybindings Support Vim-mode keybindings can be toggled on-the-fly inside both the WYSIWYM and raw Markdown editor panes: * **Activation**: Toggle via the initialization option `vimMode: true` or by calling the dynamic `setVimMode(enabled)` API. * **Dynamic Reconfiguration**: The keybindings are managed through a CodeMirror `Compartment` called `vimCompartment`. This allows swap-reloading the Vim keymap extensions (`import { vim } from "@replit/codemirror-vim"`) at runtime without rebuilding the editor view states. * **Fat Cursor Styling**: The block cursor in Vim Normal Mode (`.cm-fat-cursor`) is configured with `opacity: 0.6 !important` globally in `src/style.css` and in all theme skins. This ensures the characters covered by the block cursor are readable across all light and dark visual themes. ### E. Editor Lifecycle & State Management API Traven exposes a complete set of methods for programmatic editor control and SPA integration: * **`setReadOnly(boolean)`**: Toggles the editor between read-only and read-write mode using the `readOnlyCompartment.reconfigure()` pattern. Applies to both the primary WYSIWYM view and the raw source view if present. * **`isReadOnly()`**: Returns the current read-only state (`true`/`false`). * **`focus()`**: Programmatically focuses the primary editor via `this.#view.focus()`. * **`getSelection()`**: Returns the currently selected text from `state.selection.main`. * **`setSelection(anchor, head)`**: Sets the cursor position or selection range and focuses the editor. If `head` is omitted, places a caret at `anchor`. * **`getView()`**: Returns the primary CodeMirror `EditorView` instance for advanced use cases. * **`triggerSave()`**: Programmatically fires the `"save"` event with the current document value, without requiring a Cmd/Ctrl+S keypress. * **`destroy()`**: Destroys both the primary and raw `EditorView` instances and clears all registered event listeners. Essential for SPA integrations that mount/unmount editors dynamically to prevent memory leaks. ### F. Link WYSIWYM Rendering Traven renders markdown links (`[text](url)`) and autolinks (``) with inline WYSIWYM collapsing: * **Mechanism**: The `Link` node's child tree (produced by Lezer's markdown parser) is walked to identify `LinkMark`, `URL`, and `LinkTitle` children. All syntax characters (`[`, `]`, `(`, `)`, the URL, and the title) are collapsed with `Decoration.replace({})`, leaving only the visible link text styled with `.cm-wysiwym-link-anchor`. * **Autolinks**: The `Autolink` node's angle brackets (`<`, `>`) are similarly collapsed, with the URL text styled as a link anchor. * **Cursor-inside reveal**: When the cursor is within a link's range (`cursorHead >= node.from && cursorHead <= node.to`), all syntax is revealed for editing. This follows the same pattern used for bold, italic, and all other inline decorations. * **Title tooltips**: If a link has a title attribute (`[text](url "title")`), the title is extracted from the `LinkTitle` node, stripped of surrounding quotes, and set as a native `title` attribute on the decoration's `` element. This provides a browser-native hover tooltip. * **Ctrl/Cmd+Click**: A `domEventHandlers` extension intercepts clicks with `ctrlKey` or `metaKey` held. If the click position falls within a `Link` or `Autolink` node, the URL is extracted and opened in a new tab via `window.open(url, "_blank", "noopener,noreferrer")`. * **Delimiter skip**: Arrow key navigation across collapsed link boundaries is handled by `delimiter-skip.js`. Left/right arrow keys skip over the `[`, `](url)` collapsed regions so the cursor jumps directly between the link text and the surrounding content. ### G. Image Insertion Modal Traven provides a manual image insertion path complementing the existing optimistic drag/drop/paste uploader (`src/images.js`): * **Modal trigger**: The `image` toolbar button (`.btn-image`) opens `openImageModal()` from `src/toolbar/modal.js`. * **Two insertion paths**: - **Direct URL**: Enter an image URL and optional alt text. Inserts `![alt](url)` at the cursor. - **File Upload**: If the host application configured `onUploadImage(file)`, the modal shows a file picker. Selecting a file disables the URL field (mutual exclusivity). The Insert button changes to "Uploading…" while the upload promise resolves, then inserts `![alt](finalUrl)`. * **Upload handler access**: The modal retrieves the upload callback via `editor.getUploadHandler()`, a public getter that returns the `onUploadImage` function or `null`. * **Error handling**: If the upload promise rejects, the modal shows a red error message and re-enables the Insert button, allowing the user to retry or switch to URL input. * **Selection pre-fill**: If text is selected when the modal opens, the alt text field is pre-filled with the selection content (mirrors the link modal behavior). * **Drag suppression**: The `ImageWidget` in `images.js` sets `draggable="false"` and intercepts `mousedown` to prevent native browser drag ghosts from disrupting CodeMirror text selection. ### H. Interactive Table Editor & WYSIWYM Widget Traven includes a graphical Table Editor and full WYSIWYM rendering for GFM tables: * **Interactive Table Widget (`TableWidget`)**: - Resides in `src/wysiwym.js`. - Parses raw table blocks when the cursor is outside using the shared helper `parseMarkdownTable`. - Replaces raw Markdown with a clean, theme-styled HTML `` DOM element. * **Table Editor Modal (`openTableModal`)**: - Resides in `src/toolbar/modal.js` and is activated either by clicking a rendered `TableWidget` or via the `table` toolbar tool (`.btn-table`). - Provides a spreadsheet-like GUI editor containing a `contenteditable` grid. - Features toolbar actions to Add Column, Delete Column, Add Row, and Delete Row, rendered using customized Phosphor SVG icon definitions. - Implements keyboard focus trapping and custom `Tab` / `Shift+Tab` / `Enter` navigation to move seamlessly between grid cells and modal buttons. * **GFM Table Parsing & Serialization**: - **Parsing**: `parseMarkdownTable(tableText)` uses a character-by-character scanner to correctly parse header columns, cell contents, and column alignments (`left`, `center`, `right`). It handles escaped pipes (`\|` -> `|`) inside cell data and defaults to `"left"` alignment if not specified. - **Serialization**: `serializeTableToMarkdown(headers, rows, alignments)` reconstructs the table string. It escapes raw pipes in cells (`|` -> `\|`), uses explicit separator column colons (`:---`), and aligns column paddings dynamically to output clean, reader-friendly Markdown. * **WYSIWYM Cell Formatting & Alignments**: - **Inline formatting**: Cells run through a `renderInlineMarkdown` helper converting bold (`**`, `__`), italics (`*`, `_`), inline code (`` ` ``), links (`[text](url)`), and images (`![alt](url)`) into rendered markup. - **Theme highlight sync**: Highlight tokens (`==`) are converted into `` so they inherit visual highlights directly from the active editor stylesheet/skin instead of defaulting to generic browser-native yellow `` styling. - **Alignment styling**: Headers and cells dynamically apply `style.textAlign` matching the parsed column alignment settings. - **Interactive Links**: Clicks on link anchors (``) in the WYSIWYM cells bypass the modal launch, letting the browser follow the link in a new tab. - **Min cell dimensions**: Both the editor widget cells and the HTML Preview cells apply `height: 38px` and `box-sizing: border-box` across all skins (`skin-light.css`, `skin-colorful.css`, `skin-dark.css`) to prevent blank cells from visually collapsing. ### I. Lezer-based YAML Frontmatter Parsing To prevent common regex matching bugs on mixed CRLF/LF line endings, nested `---` tokens, or leading horizontal rules, Traven relies on Lezer's syntax tree to parse and strip YAML frontmatter: * **Canonical Node Check**: The editor maps frontmatter to the `"Frontmatter"` syntax node emitted by `@codemirror/lang-yaml` (`yamlFrontmatter`). * **Validation Guard**: In `#fallbackRender`, frontmatter is stripped only if the node starts at index `0` and contains at least two `"DashLine"` tokens. This ensures a single `---` at the beginning of the file is correctly rendered as a horizontal rule rather than treated as a truncated frontmatter block. ### J. Unified Lezer-based List Parsing & Toggling To prevent subtle divergence bugs between the WYSIWYM decorations builder (`src/wysiwym.js`) and editor commands (`insertList`, `removeFormatting` in `src/index.js`), list matching is unified via Lezer syntax tree analysis: * **`getListPrefixAt(state, pos)`**: Checks if the line contains a list item (`ListItem`) starting on that line. It performs a pre-order traversal starting at the first non-whitespace character after blockquote prefixes to locate the `ListMark` and `TaskMarker` nodes. Returns `{ type: 'ol' | 'ul' | 'task', from: number, prefixLen: number, taskMarker }`. * **`getListStrippingRanges(state, from, to)`**: Resolves precise list stripping offsets for selections. It handles list indentations correctly, but preserves blockquote prefixes (`>`) at the start of the line. * **`isInCodeBlock(state, pos)`**: Prevents editor commands from inserting list formatting when the selection starts inside a fenced code block or inline code text. * **Benefits**: Resolves pre-existing bugs such as incorrect parsing of star/plus list bullets (`*`, `+`), double-insertions on negative numbers (`-3.14`), and formatting corruptions inside code blocks. ### K. Custom Image Shortcode [image ...] Parser & Widget Traven includes support for an optional, self-closing `[image src="..." align="..." size="..." caption="..." class="..." alt="..."]` shortcode system: * **Optional & Backwards-Compatible**: This custom shortcode is completely optional. Traven remains fully backwards-compatible with standard Markdown image syntax (`![alt](src)`). Legacies images will parse, render, and compile exactly as they did previously. * **Lezer Custom Inline Parser (`src/shortcode-parser.js`)**: Implements a custom `@lezer/markdown` inline parser that detects the `[image` tag, scans for key-value attribute pairs (normalizing single, double, or unquoted values), and builds a structured AST subtree with nodes like `ImageShortcode`, `ShortcodeMark`, `ShortcodeTagName`, `ShortcodeAttributeName`, and `ShortcodeAttributeValue`. It is integrated into the CodeMirror markdown configuration inside `src/index.js`. * **WYSIWYM Widget Rendering**: The `ImageShortcodeWidget` in `src/wysiwym.js` collapses the shortcode text block into a styled block preview widget showing the image thumbnail/element with custom sizing, alignment styling (via auto-margins to preserve CodeMirror coordinate mapping), and badges, while hiding the raw code when the cursor is outside. * **Fallback HTML Compilation**: The `#fallbackRender` method compiles `[image]` shortcodes into high-quality semantic `` elements with mapped attributes and class names (such as `.traven-image-shortcode`, `.align-[alignment]`, and `.size-[size]`). In order to maintain a separation of concerns, the renderer outputs **zero inline styles**, delegating layout, width, float, and margin styling entirely to the skin stylesheets. * **Toolbar Toggle**: The "Insert Image" toolbar modal features a sliders-icon toggle to dynamically switch between Advanced mode (inserting custom `[image]` shortcodes with fields for alt text, captions, class names, alignments, and sizes) and Legacy mode (inserting standard `![alt](src)` Markdown). * **Delimiter Skip Integration**: Delimiter skip logic in `src/delimiter-skip.js` detects `ImageShortcode` syntax boundaries and allows arrow keys to skip across the delimiters (jump to first attribute when entering, skip closing brackets when exiting). ### L. Custom [component] Shortcode & Alias System (Blockquotes, Pullquotes, Generic Cards) Traven supports a flexible, block-level custom component shortcode system that wraps nested text, supporting attributes and aliases: * **Lezer Parser Extension (`src/component-parser.js`)**: Implements a paired-tag inline scanner that identifies opening `[component]` and closing `[/component]` syntax boundaries. It parses key-value attributes (e.g. `name`, `author`, `source`) into a structured AST subtree containing `ComponentShortcode`, `ComponentShortcodeOpen`, `ComponentShortcodeClose`, `ComponentShortcodeBody`, `ComponentShortcodeTagName`, and attribute name/value tokens. * **Shorthand Aliases & Syntax Normalization**: To optimize writer workflows, the parser and editor natively translate short-syntax attributes and custom tag aliases: - Short Attribute: `[component="blockquote"]` is normalized to `[component name="blockquote"]`. - Shorthand Quote Aliases: `[quote author="..." source="..."]...[/quote]` and `[blockquote author="..." source="..."]...[/blockquote]` map to `blockquote` under the hood. - Shorthand Pullquote Alias: `[pullquote]...[/pullquote]` maps to `pullquote` under the hood. * **WYSIWYM Widget Rendering**: The `ComponentShortcodeWidget` in `src/wysiwym.js` collapses the raw tags when the cursor is outside, rendering a styled preview panel. It features a mouse hover edit-trigger overlay. Clicking the component or the overlay button launches the interactive Component Modal dialog to modify attributes or body content. * **Twig-Compatible Fallback Compilation**: In `#fallbackRender`, components are parsed and converted to high-quality semantic HTML/Twig containers with **no inline styles**: - **Blockquotes**: Renders as `
[inner HTML]
— Author, Source
` if `author` or `source` is defined; otherwise, just the `
`. - **Pullquotes**: Renders as `
[inner HTML]
`. - **Generic/Fallback Cards**: Any generic or unknown component names (like `[component="info"]` or `[component="warning"]`) fall back to card layouts: `
[inner HTML]
`, allowing theme developers to target them with stylesheet rules. * **Delimiter Skip Integration**: Delimiter skipping in `src/delimiter-skip.js` allows arrow keys to skip over opening/closing delimiters and jump inside the block content smoothly. ### M. Custom Video Shortcode [video ...] Parser & Widget Traven includes native support for an optional `[video src="..." align="..." size="..." caption="..." class="..."]` shortcode system: * **Lezer Custom Inline Parser (`src/video-parser.js`)**: Implements a custom `@lezer/markdown` inline parser that detects the `[video` tag, parses key-value attributes, and builds a structured AST subtree containing `VideoShortcode`, `VideoShortcodeMark`, `VideoShortcodeTagName`, and attribute name/value tokens. It is integrated into the CodeMirror markdown parser inside `src/index.js`. * **WYSIWYM Widget Rendering**: The `VideoShortcodeWidget` in `src/wysiwym.js` collapses the raw shortcode text when the cursor is outside. It renders a clean placeholder card indicating the video's detected platform type (YouTube, Vimeo, or Video File) and URL, alongside an edit icon. Clicking the widget or edit icon launches the interactive Video Modal to modify attributes. * **Fallback HTML Compilation**: The `#fallbackRender` method compiles `[video]` shortcodes into high-quality semantic HTML structures with **zero inline styles**: - **YouTube**: `` - **Vimeo**: `` - **Direct/Local Video Files**: `` - **Containers**: Wrapped in `
` containing a `
` if a caption is present; otherwise, wrapped in a `
`. * **Toolbar Button**: The video toolbar tool (`.btn-video`) opens `openVideoModal()` from `src/toolbar/modal-video.js` allowing users to insert or edit video shortcodes with explicit alignment, size, class, and caption fields. * **Delimiter Skip Integration**: Delimiter skipping in `src/delimiter-skip.js` automatically detects `VideoShortcode` syntax boundaries, allowing arrow keys to jump inside/across the delimiters smoothly. ### N. Custom Audio Shortcode [audio ...] Parser & Widget Traven includes native support for an optional `[audio src="..." align="..." size="..." caption="..." class="..."]` shortcode system: * **Lezer Custom Inline Parser (`src/audio-parser.js`)**: Implements a custom `@lezer/markdown` inline parser that detects the `[audio` tag, parses attributes, and builds a structured AST subtree containing `AudioShortcode`, `AudioShortcodeMark`, `AudioShortcodeTagName`, and attribute name/value tokens. * **WYSIWYM Widget Rendering**: The `AudioShortcodeWidget` in `src/wysiwym.js` collapses the raw shortcode text when the cursor is outside. It renders a clean placeholder card displaying the audio icon, the source URL/file, and the caption, with a click-to-edit option. Clicking the widget launches the interactive Audio Modal. * **Fallback HTML Compilation**: The `#fallbackRender` method compiles `[audio]` shortcodes into `