Lines & Arrows

Lines & Arrows is a sequence-diagram language, SVG renderer, and visual editor. Its readable source is the durable format shared by people, agents, the viewer, and the editor.

Website · Constructor · Showcase · Syntax reference · Agent guide

The JavaScript runtime has zero dependencies and includes TypeScript declarations. The current 0.12 line is under active development before 1.0; minor releases may change its contracts.

Browser modules target current stable Chromium. The syntax module and CLI run on Node.js 22 or newer without DOM globals.

Browser

Load the registered web component from jsDelivr:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/[email protected]"
></script>

<lines-and-arrows theme="auto">
  @Client
  @API

  Client -> API: Start
  API --> Client: Complete
</lines-and-arrows>

Diagram source inside HTML is text content, so generated embeds must escape &, <, and >. The element's source property and renderDiagram() accept raw diagram source.

Set mode="edit" to open the visual editor. The Constructor produces complete HTML for themes, editing controls, actor selection, branding, copy source, and canvas behavior. Set copy-source="false" to hide the Copy source action. When a view sets both branding="false" and copy-source="false", the diagram starts at the top edge.

Built-in icons load from the pinned Phosphor package on jsDelivr. Allow that origin in browser content policies, or omit icon properties for offline embeds.

npm

npm install lines-and-arrows

import { renderDiagram } from "lines-and-arrows";

const source = `Customer -> API: Start job
API --> Customer: Accepted`;

renderDiagram(
  document.querySelector("#diagram"),
  source,
  { theme: "auto" },
);

Package entry points:

| Import | Purpose | | --- | --- | | lines-and-arrows | Render source as SVG in a browser | | lines-and-arrows/auto | Registers <lines-and-arrows> on import | | lines-and-arrows/element | Exports explicit element registration | | lines-and-arrows/syntax | DOM-free parsing, serialization, and validation |

Node.js 22 or newer is required for the syntax API and CLI.

The element's source property accepts diagram text. Assigning different valid source starts a fresh editor session; a syntax error throws synchronously and preserves the current diagram. Visual edits emit la-change with { source }, while rendering failures emit la-error with { error }. Undo and redo are built into edit mode.

Diagram source

@Customer
  icon user

@API
  icon cloud
  tag public

@Worker
  icon gear

Customer -> API: Start job
API -> Worker: Dispatch

critical Job execution
  Worker -> Worker: Process
  Worker --> API: Completed

gap A few moments later

API --> Customer: Job complete

The syntax reference defines actors, messages, arrow forms, groups, sections, gaps, header comments, escaping, validation, and canonical serialization. The agent guide provides a compact authoring and embedding workflow.

Validation

Validate a file or standard input with the published CLI:

lines-and-arrows diagram.txt
lines-and-arrows --json diagram.txt
lines-and-arrows - < diagram.txt

Use validate, parse, and serialize from lines-and-arrows/syntax in JavaScript.

Development

npm ci
npm run check
python3 -m http.server 4173

The interactive development demo is available at http://localhost:4173/demo/.

Publishing

Stable npm releases are produced by the release workflow from an annotated vX.Y.Z tag whose commit is already on remote main. Release preparation runs npm ci and npm run check. After npm publication, npm run website:prepare synchronizes the website with the package version for its independent deployment.

License

MIT. Phosphor Icons and Prism notices are recorded in THIRD_PARTY_NOTICES.md.