Codie

Modular code display and editing package for the web.

Overview

Codie is a lightweight, modular code highlighter and editor that bridges the gap between static code display and full in-browser IDEs. Built with vanilla JavaScript, it provides syntax highlighting, live editing, and seamless integration with reactive frameworks like Vibe.

Vision: Codie is a spectrum from static highlighter to full in-browser IDE:

Minimal (vanilla)     →     Editor     →     Full REPL (vibe-powered)
highlight + format    +editable             +live output, inspect,
                      +numberedRows          visual editing, zero-build HMR

Features

Core Features

• Syntax Highlighting: HTML, CSS, JavaScript, JSON, shell and Python, detected from the code itself; YAML (yaml/yml) and Markdown (markdown/md, fenced blocks drawn in their own language) when named. Any other language draws as escaped plain text
• Editable Mode: Transform static code into a live editor with textarea overlay
• Line Numbers: Optional numbered rows for code reference
• Diff Mode: Diff a before text against the code, drawn with the same highlighter
• Its Own Element: <codie> is the block; <template codie> holds HTML the browser must not parse
• Language Modes: Pin a language via attributes (highlight-html, highlight-css, highlight-js, highlight-json)
• Dark/Light Themes: Toggle with [dark] attribute
• Runtime State Toggle: Change features dynamically via codieRef.editable, codieRef.numberedRows

Editing Features

• Tab Handling: Tab key inserts 2 spaces
• Multi-line Indent: Select multiple lines + Tab indents all
• Outdent: Shift+Tab removes indentation
• Live Preview: onEdit callback fires on every change
• Error Handling: onError callback for execution failures

Installation

npm install @ape-egg/codie

Usage

Basic Syntax Highlighting

<link rel="stylesheet" href="@ape-egg/codie/codie.css" />
<script type="module">
  import codie from '@ape-egg/codie';

  codie();
</script>

<codie>
  const greet = (name) => `Hello, ${name}!`;
</codie>

codie() with no argument takes the first <codie> or [codie] element in the document.

HTML Inside the Block

The browser parses markup written inside <codie>. Put HTML in a <template codie> instead, so it reaches codie as text:

<template codie>
  <div>
    <p>Hello, world!</p>
  </div>
</template>

The codie attribute makes any element a codie instance; <codie> needs none.

Editable Code with Line Numbers

import codie from '@ape-egg/codie';

const editor = codie('codie');
editor.editable = true;
editor.numberedRows = true;

Live Preview with onEdit

const outputRef = document.querySelector('output');

const editor = codie('codie');
editor.editable = true;
editor.onEdit = ({ formatted, raw }) => {
  outputRef.innerHTML = formatted;
};

Diff Mode

const view = codie({ el, diff: true, before: previous });

view.code = draft; // redraws the diff
view.before = other; // redraws the diff
view.diff = false; // back to a plain view of the same text
view.editable = true; // edit the after text; removed rows hide, added rows follow

Both texts are highlighted whole by codie's own highlighter, then split into rows. Changed rows come in runs, each run's added block above its removed block. A removed and an added line are paired as the same line edited when at least half their words (punctuation not counted) survive, and only then are their changed words marked. With numberedRows the rows carry their before and after line numbers. The whole diff renders in one go, like the plain view.

diff(before, after, language?, { more }?) from @ape-egg/codie/diff returns the rows as HTML for use outside an instance. Given more, unchanged lines further than three from a change fold into one full-width .codie-diff-fold row that reads ... 12 more lines ... with more as its words. The row is a <details> holding the lines it stands for, so a click opens them in place with no script.

Language-Specific Highlighting

<!-- HTML, with its <script>, <style> and on* handlers -->
<template codie highlight-html>...</template>

<!-- CSS: stylesheets or bare declaration lists -->
<codie highlight-css>...</codie>

<!-- JavaScript -->
<codie highlight-js>...</codie>

<!-- JSON -->
<codie highlight-json>...</codie>

<!-- Detected from the code: HTML, CSS, JavaScript, JSON, shell, Python or plain text (default) -->
<codie>...</codie>

A language set on the instance (codieRef.language = 'yaml') or passed to highlight(code, language) / diff(before, after, language) can be any of html, css, js, json, python, shell, yaml, yml, markdown, md or text. A language codie has no highlighter for, such as toml, draws as escaped plain text.

API

codie(selector | element | config)

Initialize a codie instance.

Parameters:

• selector (string): Query selector for the codie element — codie for the element, [codie] for an attributed one
• element (Element): DOM element reference
• config (object): Configuration object with optional el, editable, numberedRows, foldable, diff and before properties; without el the element is the first codie, [codie] in the document

Returns: Codie instance proxy

Instance Properties

const editor = codie('codie');

// Get/set code content
editor.code; // Get current code
editor.code = '<div>New code</div>'; // Set code (updates display + textarea)

// Toggle features
editor.editable = true; // Enable editing
editor.numberedRows = true; // Show line numbers
editor.foldable = false; // Disable code folding (experimental)
editor.diff = true; // Diff `before` against the code
editor.before = 'old code'; // Set the before text (redraws when diffing)

// Callbacks
editor.onEdit = ({ formatted, raw }) => {
  // formatted: cleaned up for display
  // raw: exact code content
};

editor.onError = (error) => {
  // Handle errors during editing
};

Exported Utilities

import {
  highlightHTML,
  highlightJS,
  highlightCSS,
  highlightJSRaw,
  escapeHTML,
  unescapeHTML,
  formatDocument,
  normalizeInlineWhitespace,
  ATTR,
  CLASS,
} from '@ape-egg/codie';

Attributes

Container Attributes

A <codie> element is an instance by its tag. The attributes below go on it, or on any other element carrying codie:

• codie - Marks an element that is not <codie> as an instance, <template codie> above all
• dehydrate - Skip initialization (for documentation)
• highlight-html - Highlight as HTML, including embedded <script>, <style> and on* handlers
• highlight-css - Highlight as CSS
• highlight-js - Highlight as JavaScript
• highlight-json - Highlight as JSON
• none of the above - Detect the language from the code (HTML, CSS, JavaScript, JSON, shell, Python or plain text)
• dark - Apply dark theme

Runtime Attributes (applied by codie)

• codie-editable - Applied when editable mode is active
• codie-numbered - Applied when line numbers are shown
• codie-foldable - Applied when folding is enabled (experimental)
• diff - Applied when diff mode is on

Context Variables

Codie sizes itself from CSS custom properties set on a parent, so it lines up with whatever layout system surrounds it. Each one has a fallback:

• --unit (4px) - Spacing unit; line height is 6 units, padding 4 units
• --font-mono (Geist Mono stack) - Font family

Architecture

Codie uses a layered approach with CSS Grid:

1. Display Layer (<pre>) - Syntax-highlighted code
2. Textarea Layer (optional) - Editable overlay when editable = true
3. Line Numbers (optional) - Positioned overlay when numberedRows = true

All layers are synchronized via a reactive proxy that updates the DOM when properties change.

Vibe Integration

Codie pairs naturally with Vibe for live, reactive code editing:

import { init } from '@ape-egg/vibe';
import codie from '@ape-egg/codie';

init({ output: '' });

const editor = codie('template[codie]');
editor.editable = true;
editor.onEdit = ({ formatted }) => {
  $.output = formatted;
};

<template codie>
  <p>Edit me!</p>
</template>

<output>@[output]</output>

Roadmap

Implemented

• ✓ Syntax highlighting (HTML, CSS, JS, JSON, shell, Python, YAML, Markdown) with language detection and a plain-text fallback
• ✓ Editable mode with textarea overlay
• ✓ Line numbers
• ✓ Tab handling (insert spaces, multi-line indent, outdent)
• ✓ onEdit/onError callbacks
• ✓ Template support
• ✓ Language modes
• ✓ Dark/light themes
• ✓ Diff mode

Planned

• Self-documenting REPL (execute code from editor)
• Smart script execution (only re-run when changed)
• Vibe exclusion zones (prevent parent vibe from watching preview)
• Hot state preservation (preserve state across re-execution)
• Code folding (deferred due to complexity with editable mode)
• Inspect mode (click preview element to highlight code)
• Visual editing (drag-drop reorder in preview)

License

MIT