Client-Side Extensibility

Kazari outputs plain HTML with consistent CSS classes, data attributes, and ARIA attributes. Custom JavaScript and CSS can interact with any code block without a Go-side API. The DOM is the contract.

Event delegation pattern

All of Kazari's built-in JS uses event delegation on document. Follow the same pattern for consistency and to handle dynamically inserted blocks:

1
document.addEventListener('click', function(e) {
2
  var btn = e.target.closest('.kazari-block .my-custom-btn');
3
  if (!btn) return;
4
  var block = btn.closest('.kazari-block');
5
  if (!block) return;
6
  // interact with the block
7
});

Use .closest() to find the nearest matching ancestor. This works regardless of how deeply nested the click target is (e.g., clicking an SVG path inside a button).

DOM structure

Every code block follows this hierarchy:

1
.kazari-block                          Root container
2
  └─ .frame[data-lang="go"]          Frame wrapper (editor or terminal)
3
      ├─ .kz-toolbar                 Toolbar (editor frames)
4
      │   ├─ .kz-toolbar-left        Language badge + title
5
      │   │   ├─ .kz-lang            Language label
6
      │   │   ├─ .kz-file-icon       File icon (if enabled)
7
      │   │   └─ .kz-title           File title
8
      │   └─ .kz-toolbar-right       Action buttons
9
      │       ├─ .kz-copy-btn        Copy button
10
      │       ├─ .kz-wrap-btn        Wrap toggle
11
      │       ├─ .kz-font-controls   Font +/- (visible in fullscreen only)
12
      │       ├─ .kz-fs-btn          Fullscreen toggle
13
      │       └─ .kz-collapse-toggle Collapse toggle (if threshold enabled)
14
      │
15
      ├─ .kz-fs-hint                 "Press Esc to exit" hint
16
      │
17
      └─ pre[data-language="go"]     Code container
18
          └─ code                    Token wrapper
19
              └─ .kz-line            One per line
20
                  ├─ .kz-gutter > .kz-ln   Line number
21
                  └─ .kz-code           Line content (token spans)

Terminal frames use .kz-terminal-header instead of .kz-toolbar, with .kz-terminal-actions for buttons.

Finding elements

Find the code block from any child element

1
var block = element.closest('.kazari-block');

Get the language

1
var frame = block.querySelector('.frame');
2
var lang = frame.getAttribute('data-lang'); // "go", "javascript", etc.

Get the raw source code

1
var copyBtn = block.querySelector('.kz-copy-btn');
2
var code = copyBtn.getAttribute('data-code').replace(/\x7f/g, '\n');

The data-code attribute encodes newlines as \x7f (DEL character). Replace them to get the original source.

Get the line count

1
var count = parseInt(block.getAttribute('data-lines'), 10);

Get all lines

1
var lines = block.querySelectorAll('.kz-line');
2
lines.forEach(function(line) {
3
  var content = line.querySelector('.kz-code').textContent;
4
});

Reading state

Is the block collapsed?

1
var isCollapsed = block.classList.contains('kz-collapsed');

Is word wrap enabled?

1
var pre = block.querySelector('pre');
2
var isWrapped = pre.classList.contains('wrap');

Is the block in fullscreen?

1
var isFullscreen = document.fullscreenElement === block;

Is a line marked/highlighted?

1
var line = block.querySelector('.kz-line:nth-child(3)');
2
line.classList.contains('mark');     // highlighted
3
line.classList.contains('ins');      // inserted (diff)
4
line.classList.contains('del');      // deleted (diff)
5
line.classList.contains('focused');  // focus line

Modifying state

Toggle word wrap programmatically

1
var pre = block.querySelector('pre');
2
pre.classList.toggle('wrap');

Copy code programmatically

1
var copyBtn = block.querySelector('.kz-copy-btn');
2
var code = copyBtn.getAttribute('data-code').replace(/\x7f/g, '\n');
3
navigator.clipboard.writeText(code);

Enter/exit fullscreen programmatically

1
// Enter
2
block.requestFullscreen();
3
4
// Exit
5
if (document.fullscreenElement) {
6
  document.exitFullscreen();
7
}

Expand/collapse programmatically

1
block.classList.toggle('kz-collapsed');

Set font scale in fullscreen

1
block.style.setProperty('--kz-fs-font-scale', 2.0);
2
localStorage.setItem('kz-fs-font-scale', 2.0);

Listening for state changes

Collapse state

1
var observer = new MutationObserver(function(mutations) {
2
  mutations.forEach(function(m) {
3
    if (m.attributeName === 'class') {
4
      var collapsed = m.target.classList.contains('kz-collapsed');
5
      console.log('Collapsed:', collapsed);
6
    }
7
  });
8
});
9
observer.observe(block, { attributes: true, attributeFilter: ['class'] });

Fullscreen state

1
document.addEventListener('fullscreenchange', function() {
2
  if (document.fullscreenElement && document.fullscreenElement.classList.contains('kazari-block')) {
3
    console.log('Entered fullscreen');
4
  } else {
5
    console.log('Exited fullscreen');
6
  }
7
});

Tab changes in code groups

1
document.addEventListener('click', function(e) {
2
  var tab = e.target.closest('.kz-group-tabs button[role="tab"]');
3
  if (!tab) return;
4
  console.log('Tab switched to:', tab.textContent);
5
});

Inject a button into the toolbar after Kazari renders:

1
document.querySelectorAll('.kazari-block .kz-toolbar-right').forEach(function(toolbar) {
2
  var btn = document.createElement('button');
3
  btn.className = 'kz-copy-btn'; // reuse existing button styling
4
  btn.setAttribute('title', 'Download code');
5
  btn.innerHTML = '<svg>...</svg>';
6
  toolbar.appendChild(btn);
7
});

Then handle clicks via event delegation:

1
document.addEventListener('click', function(e) {
2
  var btn = e.target.closest('.kazari-block .my-download-btn');
3
  if (!btn) return;
4
  var block = btn.closest('.kazari-block');
5
  var copyBtn = block.querySelector('.kz-copy-btn');
6
  var code = copyBtn.getAttribute('data-code').replace(/\x7f/g, '\n');
7
  var blob = new Blob([code], { type: 'text/plain' });
8
  var a = document.createElement('a');
9
  a.href = URL.createObjectURL(blob);
10
  a.download = 'code.txt';
11
  a.click();
12
});

Data attributes reference

Element	Attribute	Value
`.kazari-block`	`data-lines`	Line count (e.g., `"15"`)
`.frame`	`data-lang`	Language identifier (e.g., `"javascript"`)
`pre`	`data-language`	Language identifier
`.kz-copy-btn`	`data-code`	Source code (newlines as `\x7f`)
`.kz-copy-btn`	`data-copied`	Success message text
`.kz-wrap-btn`	`data-enable`	"Enable word wrap" label
`.kz-wrap-btn`	`data-disable`	"Disable word wrap" label
`.kz-collapse-btn`	`data-expand`	Expand button text
`.kz-collapse-btn`	`data-collapse`	Collapse button text
`.kz-collapse-btn`	`data-expanded-msg`	Screen reader announcement
`.kz-collapse-btn`	`data-collapsed-msg`	Screen reader announcement
`.kz-file-icon`	`data-ext`	File extension (e.g., `"js"`)
`.kz-group`	`data-sync`	Tab sync key for cross-group sync
`.kz-line .kz-code`	`data-label`	Marker label text

CSS custom properties

Override any --kz-* variable in a stylesheet to change Kazari's appearance without touching Go code. The full list is in the CSS variables reference. Key ones for JS interaction:

Variable	Purpose	Set by
`--kz-fs-font-scale`	Font scale multiplier in fullscreen	JS (fullscreen.js)
`--kz-indent`	Hanging indent per line	Go renderer (inline style)
`--kz-editor-bg`	Code block background	Theme system
`--kz-editor-fg`	Code block foreground	Theme system

localStorage keys

Key	Purpose	Format
`kz-fs-font-scale`	Persisted font scale for fullscreen	Float (e.g., `"1.3"`)
`kz-tabs-{syncKey}`	Selected tab index for synced code groups	Integer (e.g., `"0"`)

The pattern

Kazari exposes structured data as DOM attributes (data-lang, data-lines, data-ext, CSS classes, ARIA states). CSS selectors replace AST queries. Event delegation replaces lifecycle hooks. MutationObserver replaces state-change callbacks. CSS custom properties override every visual default.

Per-language styling is a CSS selector, not an API call:

1
.kazari-block .frame[data-lang="python"] .kz-toolbar {
2
  border-bottom-color: #ffd43b;
3
}

Post-Render Callbacks for Go-side HTML modification after rendering
Custom Highlighters for swapping tokenization engines or accessing raw tokens
CSS Custom Properties for the full styling contract