@tin.so/core 0.1.0 → 0.3.0

package/README.md

@@ -1,33 +1,123 @@
 # @tin.so/core
 
-Renders code images from a JSON spec. The pipeline is `spec → Shiki tokens → layout → SVG → PNG` and needs no browser: the layout places every character on a monospace grid with the metrics of the bundled fonts, and [resvg](https://github.com/linebender/resvg) (WebAssembly) rasterizes the SVG. The same code runs in Node and in the browser.
+Renders code images from a JSON spec, to SVG and PNG. One image can show several snippets: windows next to each other or below each other, panes in a window, and popovers that point to a word. It has 14 editor themes such as GitHub, Dracula, Nord and Catppuccin, a default background for each theme and mode, backgrounds as CSS gradients, line highlights, text styles and colors, tabs with file icons, and fixed aspect ratios for social media.
+
+The pipeline is `spec → Shiki tokens → layout → SVG → PNG` and needs no browser. The layout puts every character on a monospace grid with the metrics of the bundled fonts, and [resvg](https://github.com/linebender/resvg) (WebAssembly) rasterizes the SVG. The same code runs in Node and in the browser.
+
+This package is the renderer of the [tin.so](https://tin.so) web editor and of the [`tin` CLI](https://www.npmjs.com/package/tin.so). To make images from the command line, use the CLI.
+
+## Installation
+
+```bash
+npm install @tin.so/core
+```
+
+Node 22.18 or later.
+
+## Usage
 
 ```ts
+import { writeFile } from "node:fs/promises";
 import { render } from "@tin.so/core/node";
 
 const png = await render({
-  theme: "vercel",
+  theme: "github",
   windows: [
     {
-      titleBar: false,
       tabs: true,
-      split: "row",
+      titleBar: false,
       panes: [
-        { title: "main.ts", code: 'import plans from "./plans.toml";' },
+        {
+          title: "main.ts",
+          code: 'import plans from "./plans.toml";\n\nplans.free.price;',
+          highlight: [3],
+          annotations: [
+            { line: 1, match: "plans", code: "const plans: {\n  free: { price: 0 };\n}" },
+          ],
+        },
         { title: "plans.toml", code: "[free]\nprice = 0" },
       ],
     },
   ],
 });
+
+await writeFile("plans.png", png);
+```
+
+`render(spec, { format: "svg" })` gives an SVG with the fonts inside it. `scale` sets the pixel ratio of a PNG (default 2). By default, the image contains the spec and a link that opens it in the web editor. `metadata: false` turns this off.
+
+`createLink(spec)` gives that link without an image:
+
+```ts
+import { createLink } from "@tin.so/core";
+
+const link = await createLink(spec); // https://tin.so/#spec=…
+```
+
+## The spec
+
+A spec is JSON with the image settings, its windows, the panes of each window, and the code of each pane. A spec needs only `windows`, `panes` and `code`.
+
+```json
+{
+  "$schema": "https://tin.so/schema/v1.json",
+  "theme": "dracula",
+  "windows": [{ "panes": [{ "title": "main.ts", "code": "const a = 1;" }] }]
+}
+```
+
+| Level  | Fields                                                                                                                                                                      |
+| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Image  | `theme`, `mode`, `background`, `backgroundOpacity`, `padding`, `font`, `lineNumbers`, `direction`, `gap`, `aspectRatio`, `width`, `height`, `windows`                       |
+| Window | `panes`, `split`, `titleBar`, `tabs`, `frame`, `controls`, `background`, `title`, `width`, `height`, `x`, `y`                                                               |
+| Pane   | `code`, `title`, `language`, `highlight`, `marks` (bold, italic, colors, highlighter fills), `annotations` (popovers, with an optional `background`), `icon`, `lineNumbers` |
+
+The full spec, with a description, a default and the limits of each field, is the JSON Schema at [`https://tin.so/schema/v1.json`](https://tin.so/schema/v1.json). `specJsonSchema()` gives the same schema.
+
+The `$schema` URL (`/schema/v1.json`) or the field `v` gives the version of the spec. A spec without both is version 1. A new version comes only with a change that can break a spec. New optional fields and new themes, fonts or languages come without one.
+
+The renderer ignores keys that start with `x-` in every object, so a spec can carry data of other tools.
+
+An invalid spec throws a `SpecError` that names each problem with its path, for example `windows.0.panes.0.annotations.0.match: "plnas" (occurrence 1) is not in line 1`.
+
+## API
+
+| Function                                                 | What it does                                                                               |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `render(spec, options?)`                                 | Renders a spec to PNG or SVG bytes, in Node (`@tin.so/core/node`)                          |
+| `parseSpec(input)`                                       | Checks a spec and fills in the defaults. Throws a `SpecError`                              |
+| `layout(spec, options?)`                                 | Highlights the code and places the windows, panes and popovers. Gives a `Scene`            |
+| `toSvg(scene, options?)`                                 | Writes the SVG of a scene, with or without embedded fonts and metadata                     |
+| `initPng(load)`, `svgToPng(svg, fonts, options?)`        | Loads the resvg WebAssembly once, then rasterizes an SVG                                   |
+| `loadSceneFonts(scene, loadFont)`                        | Loads the font files that a scene uses                                                     |
+| `createLink(spec, appUrl?)`, `readLink(link)`            | Writes a spec into an editor link, and reads it back                                       |
+| `encodeSpec(spec)`, `decodeSpec(encoded)`                | The compressed spec of a link, without the URL                                             |
+| `readImageSpec(image)`                                   | Reads the spec from a PNG or SVG that has the metadata. Gives `undefined` for other images |
+| `specJsonSchema()`, `SPEC_SCHEMA_URL`                    | The JSON Schema of the spec, and its URL                                                   |
+| `THEME_IDS`, `CODE_FONT_IDS`, `LANGUAGE_IDS`, `ICON_IDS` | The ids that the spec accepts                                                              |
+| `BACKGROUNDS`, `isCssBackground`                         | The background presets of the editor, and the check of a CSS background                    |
+| `themeBackground(theme, mode)`                           | The background preset that a theme uses in a mode when the spec sets no background         |
+
+### In the browser
+
+Import from `@tin.so/core`, and give the steps that read files a loader, because the browser has no file system:
+
+```ts
+import { initPng, layout, loadSceneFonts, svgToPng, toSvg } from "@tin.so/core";
+
+const scene = await layout(spec);
+// loadFont gets a path in the fonts/ directory of this package, for example "fira-code/fira-code-400.ttf"
+const fonts = await loadSceneFonts(scene, loadFont);
+await initPng(() => fetch(wasmUrl)); // the index_bg.wasm file of @resvg/resvg-wasm
+const png = await svgToPng(toSvg(scene), fonts.values());
 ```
 
 ## Scripts
 
-- `pnpm port-themes` fetches the ray.so themes at a pinned commit and writes `src/themes/*.json`.
+- `pnpm port-editor-themes` writes `src/themes/editor-themes.json` from the editor themes of Shiki, and their licenses into `EDITOR_THEMES_NOTICES.md`. It also fetches the official light variants of Dracula and Tokyo Night, which Shiki does not have, from their repositories at a pinned commit, and writes them into `src/themes/textmate/`. The list of themes is in the script.
 - `pnpm download-fonts` downloads the fonts to `fonts/` and writes their metrics to `src/fonts/fonts.generated.json`.
+- `pnpm generate-icons` writes the language icons from Simple Icons.
 
-## Attribution
+## License
 
-- The themes, the token colors and the frame styles come from [ray.so](https://github.com/raycast/ray-so) (MIT).
-- The fonts are under the SIL Open Font License, except Commit Mono (MIT). Each font directory contains its license.
-- The file icon is from [Lucide](https://lucide.dev) (ISC), the language icons from [Simple Icons](https://simpleicons.org) (CC0).
+MIT. The window style comes from ray.so (MIT), and the editor themes are under MIT or Apache 2.0 (see [EDITOR_THEMES_NOTICES.md](EDITOR_THEMES_NOTICES.md)), the file icon from Lucide (ISC), the language icons from Simple Icons (CC0), and the fonts are under the SIL Open Font License, except Commit Mono (MIT). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,65 @@
+# Third-party notices
+
+`@tin.so/core` contains work of other projects. Their licenses follow.
+
+## ray.so
+
+The style of the window (its colors, border, shadow and title bar) comes from [ray.so](https://github.com/raycast/ray-so).
+
+```
+MIT License
+
+Copyright (c) 2024 Raycast Technologies Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## Editor themes
+
+The editor themes come from their own projects, through [tm-themes](https://github.com/shikijs/textmate-grammars-themes) and Shiki. [EDITOR_THEMES_NOTICES.md](EDITOR_THEMES_NOTICES.md) lists each project with its license.
+
+## Lucide
+
+The file icon comes from [Lucide](https://lucide.dev).
+
+```
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```
+
+## Simple Icons
+
+The language icons come from [Simple Icons](https://simpleicons.org), under [CC0 1.0](https://github.com/simple-icons/simple-icons/blob/develop/LICENSE.md).
+
+## Fonts
+
+The fonts in `fonts/` are under the SIL Open Font License 1.1, except Commit Mono, which is under the MIT License. Each font directory contains its license.