- JavaScript 100%
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.
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)andrenderSlots(slots, seed, options)expose the two halves ofencode, 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_formatorchecksum).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):
-
From the repo root,
npm version patch(orminor/major) bumps the version and creates a signedv…tag. -
git push --follow-tagspushes it. CI runs the tests, builds, and stages the core version on npm. -
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):
-
Bump the workspace version, then tag it
extras-v<version>(note:npm versionin a workspace skips its usual git commit/tag, so the tag is created explicitly — this produces a tag likeextras-v0.1.2when the workspace version becomes0.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 -
CI verifies the tag equals
extras-v+ the version inpackages/heptapod-ink-extras/package.json, runs the root test + build gate, and stages only the extras package on npm. -
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