@regmisatyam/retex 0.1.0 → 0.2.0

package/README.md

@@ -11,6 +11,11 @@ LaTeX without the toolchain. You write a small, readable markup language; ReTeX
 tokenizes, parses, validates, and renders it to **HTML**, **React**, **JSON**, or
 **PDF** — all from a single, dependency-free TypeScript library.
 
+ReTeX is **blank by default** — a plain, unstyled document, "just simple
+editing". Styling is opt-in: import a **library** with `\usepackage{...}`
+(LaTeX-style) for colors, fonts, shapes, or a full themed look. Nothing is
+imposed; you add exactly what you want.
+
 ```latex
 \name{Ada Lovelace}
 \title{Software Engineer}
@@ -27,10 +32,11 @@ tokenizes, parses, validates, and renders it to **HTML**, **React**, **JSON**, o
 
 ## Preview
 
-The three [examples](examples/) rendered to HTML (default, modern, and classic
-themes). Regenerate with `npx tsx examples/build.ts`.
+The three [examples](examples/) rendered to HTML. Each opts into a theme pack
+with a single `\usepackage{...}` line (`modern`, `compact`, `classic`).
+Regenerate with `npx tsx examples/build.ts`.
 
-| Single column (`default`) | Two column (`modern`) | Academic CV (`classic`) |
+| Single column (`modern`) | Two column (`compact`) | Academic CV (`classic`) |
 | --- | --- | --- |
 | [![software engineer](examples/rendered/software-engineer.png)](examples/software-engineer.retex) | [![two column](examples/rendered/two-column.png)](examples/two-column.retex) | [![research paper](examples/rendered/research-paper.png)](examples/research-paper.retex) |
 
@@ -44,18 +50,29 @@ set of commands (`\name`, `\job`, `\education`, `\skills`, `\section`, …), str
 theming, and four production-ready renderers.
 
 ReTeX **is not** a full LaTeX implementation. There is no math mode, no macro
-programming, no package ecosystem, no `\def`. The syntax is *LaTeX-inspired* —
-familiar braces and backslash commands — but the language is deliberately small,
-safe, and predictable. (Notably, `%` is a literal percent sign, not a comment;
+programming, no `\def`. The syntax is *LaTeX-inspired* — familiar braces and
+backslash commands — but the language is deliberately small, safe, and
+predictable. (Notably, `%` is a literal percent sign, not a comment;
 see [Syntax](docs/SYNTAX.md).)
 
+It does, however, borrow LaTeX's best idea: **packages**. The core is blank, and
+you `\usepackage{...}` exactly the styling you need — `colors`, `fonts`,
+`shapes`, or a complete theme pack like `modern`. See [Libraries](#libraries).
+
 ---
 
 ## Features
 
-- **Typography** — `\textbf`, `\textit`, `\emph`, `\underline`, `\sout`,
-  `\textcolor`, `\fontsize`, `\fontfamily`, and scoped switches (`\small`,
-  `\large`, `\Large`, `\Huge`, `\bfseries`, `\itshape`, `\ttfamily`).
+- **Blank by default** — the core ships structure + basic emphasis; everything
+  decorative is opt-in. A document with no imports renders as a clean,
+  browser-default page.
+- **Core typography** — `\textbf`, `\textit`, `\emph`, `\underline`, `\sout`,
+  `\bfseries`, `\itshape`.
+- **Libraries (`\usepackage`)** — opt into styling, LaTeX-style: `colors`
+  (`\textcolor`, `\themecolor`), `fonts` (`\fontfamily`, `\fontsize`,
+  `\small`…`\Huge`, `\ttfamily`), `shapes` (`\hrule`, `\dashrule`, …, `\vspace`,
+  `\hspace`), and theme packs `modern` / `classic` / `compact`. Activate from the
+  document **or** from code (`engine.use(...)`).
 - **Hyperlinks** — `\href{url}{label}` and `\url{url}`, with URL sanitization.
 - **Sections** — `\section` and `\subsection`.
 - **Résumé components** — `\name`, `\title`, `\email`, `\phone`, `\location`,
@@ -64,8 +81,8 @@ see [Syntax](docs/SYNTAX.md).)
   environment.
 - **Icons** — inline SVG icon set (`\icon{github}`, `\icon{linkedin}`, …),
   extensible at runtime.
-- **Theming** — four presets (`default`, `modern`, `classic`, `compact`) plus a
-  fully data-driven, deep-mergeable custom theme model.
+- **Theming** — a blank default plus opt-in presets (`modern`, `classic`,
+  `compact`) and a fully data-driven, deep-mergeable custom theme model.
 - **Plugins** — register new commands, environments, icons, renderers, or theme
   patches on a per-engine basis. Two example plugins ship in the box
   (`badgePlugin`, `ratingPlugin`).
@@ -73,6 +90,9 @@ see [Syntax](docs/SYNTAX.md).)
   React element tree, a structured JSON AST, and print-ready HTML/PDF.
 - **Editor tooling** — completion, hover docs, semantic tokens, diagnostics,
   formatting, and AST inspection via `EditorService`.
+- **Two-way preview** — opt-in `sourceMap` HTML stamps elements with source
+  offsets so a live editor can sync both ways (click preview ↔ highlight code),
+  Overleaf-style. See [`examples/playground.html`](examples/playground.html).
 - **Incremental parsing** — block-level caching for fast live preview.
 - **Security** — every text node and attribute is escaped; every URL is vetted.
   No `eval`, no `Function`, no code execution of source.
@@ -84,7 +104,7 @@ see [Syntax](docs/SYNTAX.md).)
 ## Install
 
 ```bash
-npm install retex
+npm i @regmisatyam/retex
 ```
 
 React is an **optional peer dependency** — install it only if you use the React
@@ -98,22 +118,26 @@ PDF export lazily imports `puppeteer` if present; otherwise you can supply your
 own headless-browser launcher (Playwright, a pooled Chromium, etc.) or print the
 generated HTML to PDF in the browser.
 
-The package exposes two entry points:
+The package exposes three entry points:
 
-| Import path     | Contents                                              |
-| --------------- | ----------------------------------------------------- |
-| `retex`         | The engine, pipeline, AST utilities, all renderers\*, theming, plugins, security, icons, editor, incremental compiler. |
-| `retex/react`   | The React renderer (`ReactRenderer`, `renderReact`).  |
+| Import path                  | Contents                                              |
+| ---------------------------- | ----------------------------------------------------- |
+| `@regmisatyam/retex`         | The engine, pipeline, AST utilities, all renderers\*, theming, libraries\*\*, plugins, security, icons, editor, incremental compiler. |
+| `@regmisatyam/retex/react`   | The React renderer (`ReactRenderer`, `renderReact`).  |
+| `@regmisatyam/retex/library` | Just the libraries (`colorsLibrary`, `fontsLibrary`, …) and helpers. |
 
-\* The React renderer is also re-exported from `retex`, but lives behind
-`retex/react` so the core bundle never imports React.
+\* The React renderer is also re-exported from `@regmisatyam/retex`, but lives behind
+`@regmisatyam/retex/react` so the core bundle never imports React.
+
+\*\* The libraries are also re-exported from `@regmisatyam/retex`; the
+`/library` subpath just lets you import them on their own.
 
 ---
 
 ## Quick start
 
 ```ts
-import { ReTeXEngine } from "retex";
+import { ReTeXEngine } from "@regmisatyam/retex";
 
 const engine = new ReTeXEngine();
 
@@ -141,11 +165,30 @@ const css = engine.styles();
 `engine.toHtml` accepts either a source string or a parsed `DocumentNode`, so you
 can parse once and render to several targets.
 
+That document renders as a clean, **unstyled** page. To add styling, import a
+library — from the source:
+
+```latex
+\usepackage{modern}        %% a full themed look + the color/font/shape commands
+\textcolor{#7c3aed}{Now in color}
+```
+
+…or from code:
+
+```ts
+import { ReTeXEngine, colorsLibrary, fontsLibrary } from "@regmisatyam/retex";
+const engine = new ReTeXEngine().use(colorsLibrary).use(fontsLibrary);
+```
+
+See [Libraries](#libraries) for the full catalog.
+
 ---
 
 ## A realistic résumé
 
 ```latex
+\usepackage{modern}   %% styled look + color/font/shape commands (e.g. \hspace below)
+
 %% --- header ---
 \name{Grace Hopper}
 \title{Distinguished Engineer \& Compiler Pioneer}
@@ -252,7 +295,7 @@ engine.styles();                             // the theme's CSS (for the fragmen
 Or use the stage functions directly:
 
 ```ts
-import { tokenize, parse, validate, renderHtml } from "retex";
+import { tokenize, parse, validate, renderHtml } from "@regmisatyam/retex";
 
 const { ast } = parse(tokenize(source).tokens);
 const diagnostics = validate(ast);
@@ -266,7 +309,7 @@ factory yourself, so it works with React, Preact, or any compatible runtime.
 
 ```tsx
 import React from "react";
-import { ReTeXEngine } from "retex";
+import { ReTeXEngine } from "@regmisatyam/retex";
 
 function Resume({ source }: { source: string }) {
   const engine = React.useMemo(() => new ReTeXEngine(), []);
@@ -287,8 +330,8 @@ Standalone, via the dedicated subpath:
 
 ```tsx
 import React from "react";
-import { renderReact } from "retex/react";
-import { parse, tokenize } from "retex";
+import { renderReact } from "@regmisatyam/retex/react";
+import { parse, tokenize } from "@regmisatyam/retex";
 
 const { ast } = parse(tokenize(source).tokens);
 const element = renderReact(ast, {
@@ -321,18 +364,60 @@ const pdf2 = await engine.toPdf(source, {
 
 ---
 
+## Libraries
+
+ReTeX is blank by default; **libraries** add styling, opt-in. Activate them two
+ways — and you can mix both.
+
+**From the document** (LaTeX-style, in the preamble):
+
+```latex
+\usepackage{colors}          %% \textcolor, \themecolor
+\usepackage{fonts, shapes}   %% comma-separate to import several at once
+\textcolor{#2563eb}{Now available} — \hrule
+```
+
+`\use{...}` is an alias. If you use a gated command without its library, ReTeX
+tells you exactly which `\usepackage{...}` to add.
+
+**From code** (great for app integrations):
+
+```ts
+import { ReTeXEngine, colorsLibrary, shapesLibrary } from "@regmisatyam/retex";
+
+const engine = new ReTeXEngine({ plugins: [colorsLibrary, shapesLibrary] });
+// or: new ReTeXEngine().use(colorsLibrary).use(shapesLibrary)
+engine.toHtml("\\textcolor{#2563eb}{Hi} \\hrule");
+```
+
+### Built-in libraries
+
+| Library                          | `\usepackage{…}` | Provides                                                                  |
+| -------------------------------- | ---------------- | ------------------------------------------------------------------------- |
+| `colorsLibrary`                  | `colors`         | `\textcolor`, `\themecolor`, plus a `palettes` catalog                    |
+| `fontsLibrary`                   | `fonts`          | `\fontfamily`, `\fontsize`, `\small`…`\Huge`, `\normalsize`, `\ttfamily`, plus `fontStacks` / `fontTheme` |
+| `shapesLibrary`                  | `shapes`         | `\hrule`, `\divider`, `\dashrule`, `\dotrule`, `\thickrule`, `\doublerule`, `\vspace`, `\hspace` |
+| `modern` / `classic` / `compact` | same name        | A complete styled look **plus** all three toolkits above                  |
+
+Theme packs are the quickest path to a polished document: `\usepackage{modern}`
+gives you the full look *and* every styling command. Bring your own library with
+`engine.provideLibrary(myLib)` (addressable by `\usepackage`) or `engine.use`.
+
+---
+
 ## Theming
 
-Themes are plain data, deep-merged over the default. Pass a full `Theme` or a
-partial patch.
+Themes are plain data, deep-merged over the **blank** default — so every field is
+optional, and what you don't set stays unstyled. Pass a full `Theme` or a partial
+patch.
 
 ```ts
-import { ReTeXEngine, modernTheme } from "retex";
+import { ReTeXEngine, modernTheme } from "@regmisatyam/retex";
 
 // Use a preset:
 const a = new ReTeXEngine({ theme: modernTheme });
 
-// Or a partial override (deep-merged over the default):
+// Or a partial override (deep-merged over blank):
 const b = new ReTeXEngine({
   theme: {
     name: "brand",
@@ -342,14 +427,16 @@ const b = new ReTeXEngine({
   },
 });
 
-// Swap at runtime:
+// Swap at runtime (an anonymous patch merges over the current theme):
 b.setTheme({ colors: { primary: "#059669" } });
 ```
 
-Presets: `defaultTheme`, `modernTheme`, `classicTheme`, `compactTheme` (also
-available by name via `getTheme("modern")` or the `themes` map). Every theme
-color is exposed as a CSS variable (`--retex-color-<token>`), usable from
-`\themecolor{token}{…}`.
+Presets: `blankTheme` (the default), `modernTheme`, `classicTheme`,
+`compactTheme` (also available by name via `getTheme("modern")` or the `themes`
+map). Every theme color is exposed as a CSS variable (`--retex-color-<token>`),
+usable from `\themecolor{token}{…}`. A blank theme still renders a readable
+document — the structural CSS is always emitted; only decoration is left to a
+theme/library.
 
 ---
 
@@ -360,7 +447,7 @@ theme patches. The simplest case — a custom inline command with a render
 function and no custom AST node:
 
 ```ts
-import { ReTeXEngine } from "retex";
+import { ReTeXEngine } from "@regmisatyam/retex";
 
 const engine = new ReTeXEngine();
 
@@ -384,7 +471,7 @@ engine.toHtml("\\badge{Open to work}");
 Or package it as a reusable plugin and install with `.use()`:
 
 ```ts
-import { ReTeXEngine, badgePlugin, ratingPlugin } from "retex";
+import { ReTeXEngine, badgePlugin, ratingPlugin } from "@regmisatyam/retex";
 
 const engine = new ReTeXEngine({ plugins: [badgePlugin, ratingPlugin] });
 engine.toHtml("\\badge{New} \\rating{4}");
@@ -402,7 +489,7 @@ override. See **[docs/API.md](docs/API.md)** for the full `ReTeXPlugin` contract
 All methods are pure and synchronous.
 
 ```ts
-import { EditorService } from "retex";
+import { EditorService } from "@regmisatyam/retex";
 
 const editor = new EditorService();
 
@@ -419,6 +506,70 @@ optional quick-fixes, so editors can wire up code actions and doc links.
 
 ---
 
+## Two-way preview (source mapping)
+
+Like Overleaf's SyncTeX, ReTeX can keep an editor and its live preview in sync
+in **both directions** — click an element in the preview to jump to the source
+that produced it, and move the caret in the source to highlight the matching
+element in the preview.
+
+Turn it on with the `sourceMap` render option. The HTML renderer then stamps
+every meaningful element with `data-rtx-pos="start:end"` (zero-based UTF-16
+offsets into the source) and a `data-rtx-type` (the originating node):
+
+```ts
+const engine = new ReTeXEngine();
+engine.toHtml(source, { sourceMap: true });
+// …<section data-rtx-pos="20:40" data-rtx-type="section">…
+//   <p class="retex-para" data-rtx-pos="101:130" data-rtx-type="para">
+//     Built <strong data-rtx-pos="110:128" data-rtx-type="bold">compilers</strong>.
+//   </p>…
+```
+
+`sourceMap` defaults to **off**, so exported/production HTML stays clean and
+unannotated — you only pay for the attributes when driving a live editor.
+
+A few tiny, **editor-agnostic** helpers turn those attributes into sync (they
+work with the real DOM or any object exposing `getAttribute`, so the core never
+touches `document`):
+
+```ts
+import {
+  closestSourcePos,     // preview → code: nearest annotated ancestor's span
+  pickElementForOffset, // code → preview: tightest element under the caret
+  SOURCE_POS_ATTR,
+} from "@regmisatyam/retex";
+
+// Reverse sync — click the preview, select the source it came from:
+preview.addEventListener("click", (e) => {
+  const span = closestSourcePos(e.target);
+  if (span) {
+    textarea.focus();
+    textarea.setSelectionRange(span.start, span.end);
+  }
+});
+
+// Forward sync — caret moves, highlight the matching preview element:
+function onCaretMove() {
+  const el = pickElementForOffset(
+    preview.querySelectorAll(`[${SOURCE_POS_ATTR}]`),
+    textarea.selectionStart,
+  );
+  el?.classList.add("active");
+}
+```
+
+### Try it
+
+A complete, dependency-free playground ships in [`examples/playground.html`](examples/playground.html)
+— a split editor/preview with both sync directions wired up:
+
+```bash
+npm run playground   # builds the library, serves it, and opens the demo
+```
+
+---
+
 ## Security
 
 ReTeX renders untrusted markup, so safety is built into every layer:
@@ -446,7 +597,7 @@ paragraph re-parses only that block while the rest are served from cache and
 cheaply re-positioned.
 
 ```ts
-import { IncrementalCompiler } from "retex";
+import { IncrementalCompiler } from "@regmisatyam/retex";
 
 const inc = new IncrementalCompiler();
 const { ast, diagnostics, stats } = inc.compile(source);
@@ -459,6 +610,7 @@ const { ast, diagnostics, stats } = inc.compile(source);
 
 ```bash
 npm run build       # bundle with tsup (ESM + CJS + d.ts)
+npm run playground  # build + serve the two-way preview demo
 npm run typecheck   # tsc --noEmit
 npm test            # run the test suite (vitest)
 npm run test:watch  # watch mode