The napkin-sketch API#

API hub · Quickstart · Cheatsheet

Draw without a pointer. napkin-sketch has a language, napkin script, that says what to draw one instruction a line, and a composition API that builds a graphic in code. Both write SVG and PNG, and a drawing also PDF, the app's own .skbk and an Illustrator script, with no window, no browser and no native library, from a shell, from Node, or from any language that can start a process.

Where to start. A person: API-QUICKSTART.md, then the quickstart of the category you need. An agent: docs/api/INDEX.json, which lists every page with its kind, its first paragraph and its size, and then a cheatsheet. Every verb, flag and exit code on one page: API-CHEATSHEET.md.

What it is#

• A drawing language. A napkin script is a list of instructions such as page, layer, color, rect, text and repeat, written as text by a person or an AI tool, or built as JSON by a program. It runs into a sketch book: the same pages, layers and Bezier anchors the app draws by hand, so a script's drawing opens in the app as editable work.
• A composition API. createComposition builds a page out of shapes, text, images, masks and gradients in code, and renders the one document to SVG and PNG.
• Four commands. napkin-sketch draw, check, render and verbs run scripts from a shell or a batch file, and from Python, C or anything else through standard input and one line of JSON back.
• Three package entries. @isocialpractice/napkin-sketch runs anywhere and reads no file; @isocialpractice/napkin-sketch/node reads scripts, images and books and writes files; and @isocialpractice/napkin-sketch/markdown gives the first a Markdown reader and a code highlighter, so Markdown Flow text draws as its Markdown renders and code is colored.
• The engines the tools stand on. The Eraser's cut, the Wipe Stacks and the Shape Stacker, Split, clipping masks, the Pencil and its Smear, and Liquify are functions too, which a program calls on a page with no window: The drawing engines.

What it is not#

• Not a way to open files from a script. A script names an image, a book or a linked file; the program running it reads them, and links are read only inside one folder.
• Not a font engine. Without fonts, the PNG sets text in a built-in single-stroke face, and the SVG and the PDF name the font for the reader to set. A host may hand a render font files by family (fonts, optional): then text is laid out by the fonts' own advances and kerning, and the PNG and the PDF draw each glyph as its outline. It reads TrueType and OpenType outlines; it does no shaping - no ligatures, no scripts that join.
• Not a general SVG renderer. It reads the SVG other editors write - layers, curves, gradients' stops - and says what it leaves out rather than drawing it wrong.
• Not a model. The AI helpers are skills and scripts an AI tool runs; nothing in the package calls one. They are experimental.

The categories#

How it fits together#

 text script (.napkin) --parseScript--+
                                      +--> instructions: the object form (.napkin.json)
 a program (Node, Python, C) ---------+          |
                                              evaluate
                                                 |
                              sketch book: pages, layers, Bezier marks
                                                 |
          +---------------+-------------+--------+----------+-------------------+
     sketchToSvg    sketchesToPdf     .skbk           sketchesToJsx    sketchToComposition
          |               |             |                   |                   |
         SVG             PDF    the app opens it   Illustrator runs it     composition <-- createComposition
                                                                                |
                                                                            rasterize --> PNG

• The object form is the contract. Text lowers to it, and a program in another language builds it directly as JSON, checked against the schema.
• Geometry is Bezier anchors, never samples, so every output has something exact to write and the app has something to edit.
• The outputs are the app's own writers. A script's SVG is the SVG the app exports, and its PNG goes through the composition rasterizer, the one new road, with no canvas.
• Errors are values. A script that goes wrong is reported, line and code, and whatever could be drawn still is; only the disk throws.

The ways in#

Who these pages are for#

People and agents alike. Every category has three pages: a reference for the reader with time, a quickstart that runs as written from npm or a clone, and a cheatsheet of tables, and each links to the other two and back here in its first lines. The reference pages close with a section for agents: the strings to match, the flags that make a run repeatable, and which diagnostics mean retry and which mean rewrite. An agent gets the grammar from the program rather than the prose: napkin-sketch verbs --json prints every verb, shape and diagnostic code, from the table the parser reads.

The language's version#

A script's first line names the language version it was written for: napkin 1. A version changes only when a script that ran under the old one would draw differently under the new one; a new verb or a new optional field is an addition, and keeps the version. A build refuses a script newer than it reads with version-unsupported, naming the newest it does, and reads a script with no version line as version 1, with a version-missing warning. The language's version and the package's are separate: SCRIPT_VERSION is the first, and the command line's JSON report carries both, as language and version.

How these pages are kept true#

The verb tables, the command tables, the exit codes, the schema and docs/api/INDEX.json are written by npm run api-docs from the tables the code itself reads, and the test suite fails when one is out of date. Every napkin block on these pages is run by the tests, every JSON script is checked, and every relative link is followed to a file.