README.md

A ring of brush ink with swellings and tendrils: the heptapod-ink logogram

heptapod-ink #

Write text as circular ink logograms in the style of the Heptapod B script from Arrival, and read them back. Output is plain SVG. Zero dependencies, 5,866 B raw / 3,346 B min+gzip (dist/heptapod-ink.min.js), and it runs in browsers, workers and Node.

Try it in your browser →

import { encode, decode } from "heptapod-ink";

const { svg } = encode("humans and heptapods are friends");
document.querySelector("#out").innerHTML = svg;

decode(svg).text; // "humans and heptapods are friends"

This isn't a translation of the film's language. It's an encoding inspired by its look: each phrase becomes one ring of brush ink, with swellings and tendrils that carry the message. The logogram above is the phrase "humans and heptapods are friends"; pass the SVG to decode() to read it.

⚠️ Format: the original v1 SVG output (restored) #

The SVG renderer and decoder were restored to the original v1 format (2026-10-05): encode() output is byte-identical to heptapod-ink@0.1.1 for the same text and options, and the test suite gates on that byte-identity. The brief v2 experiment (releases 0.1.2 and 0.1.3) is abandoned.

Files written by heptapod-ink 0.1.2 / 0.1.3 (the v2-era format) are NOT readable and are rejected loudly: decode() throws a LogogramError (code unknown_format or checksum) — it never silently returns wrong text. There is no v2 import. Likewise, current files could not be read by the 0.1.2/0.1.3 releases. Files from 0.1.1 and earlier are fully supported (that is the shipped format again).

Install #

npm install heptapod-ink

Or without a bundler, from a CDN. The script defines a global Heptapod:

<script src="https://cdn.jsdelivr.net/npm/heptapod-ink/dist/heptapod-ink.min.js"></script>
<script>
  const { svg } = Heptapod.encode("there is no time");
</script>

ES module from a CDN:

import { encode, decode } from "https://cdn.jsdelivr.net/npm/heptapod-ink/+esm";

API #

The core package exports exactly three things: encode, decode and LogogramError.

encode(text, options?) #

Returns { svg, slots, radius, size, checksum, compact }. The same text and options always give the same SVG.

Option Default
ink true Rough ink-edge filter.
color "currentColor" Ink colour. Inline SVGs follow the surrounding text colour.
background "none" Background fill.
seed from the text Changes the decoration (tendril curls, rotation) without changing the message.
idPrefix from the seed Prefix for the filter id, so several logograms can share a page.

decode(svg) #

Returns { text, checksum, slots }, or throws a LogogramError whose code is one of not_svg, no_viewbox, no_strokes, unknown_format or checksum.

Decoding reads only the path data, so it is unaffected by colour, filters, animation or a rotation about the centre. It does not work on raster images (PNG, screenshots, photos), or on files a vector editor has re-saved with rewritten paths.

LogogramError #

The error type thrown by decode (and for invalid encode input, as TypeError-adjacent cases: empty or non-string text throws TypeError). Its code identifies the failure; see decode above.

heptapod-ink-extras #

Everything trimmed from the core lives in the heptapod-ink-extras add-on package (also zero-dependency):

npm install heptapod-ink-extras
import { parse, textToSlots, slotsToText, renderSlots, animate } from "heptapod-ink-extras";
  • parse(svg) → { viewBox, paths, circles } using plain string parsing — handy for drawing a safe preview of an untrusted file without inserting its markup into the page (the demo does this).
  • textToSlots(text), slotsToText(slots) and renderSlots(slots, seed, options) expose the two halves of encode, for drawing individual marks or building your own renderer.
  • animate(svg, { draw, drift, spin, drawDuration, spinDuration }) post-processes a logogram with SMIL animation so a saved file animates on its own.

How the encoding works #

  • The text is packed into one large number. Text using only lowercase letters, digits, space, newline and .,?!'-:; uses a compact 46-symbol alphabet; anything else is stored as UTF-8 bytes.
  • A mode bit and a CRC-16 checksum are added, and the number is written in base 10.
  • Each digit is a slot on the ring. A slot is a swelling (none, small or large, bulging out or in) with or without an outward tendril: 5 × 2 = 10 marks.
  • The gap in the ring marks the start. Reading runs clockwise, from the stroke's blunt head to its thin tail.
  • At least 10 slots are drawn. Longer messages get more slots, and the ring grows to fit them.
  • Tendril curls, ink spatter and the ring's rotation are decoration chosen by the seed. The decoder ignores them.

The SVG is drawn exactly as in heptapod-ink@0.1.1 (byte-identical): each tendril is a closed 122-point tapered outline, the ring is one closed path (29 + 8N points per side, two decimal places), and the ring's point count doubles as a format header — so v2-era files (0.1.2/0.1.3) fail loudly with unknown_format instead of decoding to garbage.

Golden corpus #

The repository contains a frozen golden corpus of 2,096 committed logograms, stored hash-based — each entry is { text, sha256 } where sha256 is the hex SHA-256 of the exact SVG encode(text) must produce (not the SVG bytes themselves, which keeps the repository at ~4 MB instead of tens of MB) — plus two legacy fixture sets:

  • corpus/entries.jsonl.gz — the corpus (text + SVG hash per line, gzip-compressed JSONL).
  • corpus/legacy-v1.jsonl.gz — 120 fixtures generated by published heptapod-ink@0.1.1; every one must decode exactly to its stored text (positive fixtures).
  • corpus/legacy-v2.jsonl.gz — 300 SVGs snapshotted from the v2-era corpus (0.1.2/0.1.3 output); every one must be rejected loudly by the decoder (LogogramError, unknown_format or checksum).
  • corpus/generate.mjs — the seeded, deterministic generator. Running it twice produces byte-identical files (npm run corpus).

The test suite gates on the corpus: for every entry, sha256(encode(text).svg) must equal the stored hash and decode(encode(text).svg) must return the original text. The corpus files are frozen — never hand-edit or regenerate them; if encode output changes, that is a defect in the code.

Size #

Measured by npm run size on the current tree:

Metric Measured Budget
dist/heptapod-ink.min.js raw 5,866 B ≤ 8,047 B (the 0.1.1 baseline)
dist/heptapod-ink.min.js min+gzip 3,346 B ≤ 4,203 B (the 0.1.1 baseline)
Mean SVG bytes (200 typical sentences) 55,239 B (80th pct 77,127 B) informational — no SVG budget since the v1 restoration
Mean SVG bytes (full 2,096-entry corpus) 85,265 B reported only

Demo #

demo/index.html is a page that writes, animates, downloads and reads logograms. It's hosted at https://heptapod-ink.tngl.io/, running the latest 0.x release from npm.

Run it locally against your working copy:

npm install
npm run build

then open demo/index.html in a browser (it loads the local dist/ build from a file:// URL).

Development #

Node is pinned via mise in .mise.toml (22.22.0). There is no system npm; all Node commands must run through mise exec. After cloning, run:

mise trust          # trust the config once per checkout
mise install        # install the pinned Node version

Then run all commands through mise exec:

mise exec -- npm test           # codec, corpus, legacy-fixture, extras and format tests
mise exec -- npm run build      # dist/heptapod-ink.min.js + dist/heptapod-ink-extras.min.js
mise exec -- npm run size       # bundle + SVG size budgets (fails on violation)
mise exec -- npm run logogram   # regenerate assets/logogram.svg

Releasing #

The core package and heptapod-ink-extras are released independently: each has its own version and its own tag prefix, and bumping one does not touch the other. Core releases use plain v* tags; extras releases use extras-v* tags.

Core (heptapod-ink):

  1. From the repo root, npm version patch (or minor/major) bumps the version and creates a signed v… tag.

  2. git push --follow-tags pushes it. CI runs the tests, builds, and stages the core version on npm.

  3. Approve it to make it public. This asks for your npm 2FA code:

    npx npm@12 stage list heptapod-ink
    npx npm@12 stage approve <stage-id>
    

Extras (heptapod-ink-extras):

  1. Bump the workspace version, then tag it extras-v<version> (note: npm version in a workspace skips its usual git commit/tag, so the tag is created explicitly — this produces a tag like extras-v0.1.2 when the workspace version becomes 0.1.2):

    cd packages/heptapod-ink-extras
    npm version patch --no-git-tag-version
    cd ../..
    git add -A
    git commit -m "Release heptapod-ink-extras"
    git tag "extras-v$(node -p 'require("./packages/heptapod-ink-extras/package.json").version')"
    git push --follow-tags
    
  2. CI verifies the tag equals extras-v + the version in packages/heptapod-ink-extras/package.json, runs the root test + build gate, and stages only the extras package on npm.

  3. Approve it to make it public:

    npx npm@12 stage list heptapod-ink-extras
    npx npm@12 stage approve <stage-id>
    

A v* tag only ever stages the core package and an extras-v* tag only ever stages the extras package; the two flows cannot trigger each other.

Every release: bump the demo CDN pins. The hosted demo (https://heptapod-ink.tngl.io/) deploys only the demo/ folder, whose CDN fallbacks in demo/index.html are pinned to exact released versions — never @0 ranges, whose jsDelivr range-resolution cache can serve stale bytes from an older release. Update both pins to the versions you just released:

// demo/index.html
const CDN_BUILD = "https://cdn.jsdelivr.net/npm/heptapod-ink@X.Y.Z/dist/heptapod-ink.min.js";
const CDN_EXTRAS = "https://cdn.jsdelivr.net/npm/heptapod-ink-extras@X.Y.Z/dist/heptapod-ink-extras.min.js";

License #

MIT © Mads R. Havmand