Lolly Tools

Powerfully reproducible assets & tools. Deterministic, fast, open-source platform - bring your own brand.

Try it now. lolly.tools runs in the browser and installs as an app. Nothing you make ever leaves your device without your say. lolly.art is the same app on a blank brand. Desktop, mobile and command-line builds are on the releases page.

Read first. The platform is explained at lolly.tools/info, with one door each for creators, builders and operators, a quickstart, and the trust pages that back each claim with the mechanism that enforces it.

We built Lolly for ourselves. SUSE needed thousands of on-brand files, each with its name sealed inside, made without handing anything to outside services. So we built a tool that does all of it on the device, and released it as open source, like everything else we make. We keep maintaining it because we use it every day. There is no obligation: everything here works with or without us.

What is Lolly Tools

A platform that hosts a library of small, focused tools that produce deterministic creative assets. Users need no design skill, no vendor lock-in and no internet to render, and the platform is designed to add premium production-quality rendering certainty to variable data.

It's also your personal DAM - every logo, palette, font and upload lives in an on-device catalog, hydrated and supercharged by your design system and tools.

Tools can be used via a:

• Web app - installable offline progressive web app
• Mobile and Desktop installable packages.
• and of course, the Command Line - plus a full-screen terminal UI (TUI).

Why deploy Lolly in your organization?

• Hard-coded constraints of design decisions.
• Free, open-source platform - the engine, every shell, the schemas and docs are MPL-2.0. Tools and assets are just data: bring your own brand content (SUSE's tool & asset packs are proprietary - see Licensing & structure).
• Unlimited scale, No SaaS fees.
• Low-or-Zero server costs: Lolly uses local device compute.
• Builds for Mac, Windows, Linux, iOS, Android, web and the command line.
• Huge format support - 49 in, 54 out (33 round-trip; the live register is docs/site/formats-catalog.json, and tests/readme-formats.test.ts keeps these three numbers pinned to it). Export: SVG · EPS · CMYK EPS · EMF · DXF · PDF · Print PDF (CMYK) · PPTX · PNG · Animated PNG · JPEG · WebP · Animated WebP · AVIF · TIFF · CMYK TIFF · ICO · PSD · EXR · Radiance HDR · MP4 · WebM · GIF · Animated SVG · MP3 · M4A · WAV · Opus · HTML · MD · TXT · CSV · JSON · ICS · VCF · ZIP. Import adds layered PSD · PSB · XCF, HEIC, MOV · Lottie, GLB · glTF, audio & tracker (OGG · FLAC · MIDI · MOD) and live designs from Illustrator · InDesign · Figma · Penpot. EXR and Radiance HDR are floating-point HDR masters written through host.codec by tools that compute float pixels, and via the CLI - the web export picker does not offer them. AVIF encodes through the browser's own canvas.toBlob, and M4A · Opus through WebCodecs, so both depend on the browser build. Plus design tokens & palettes - import DTCG and Tokens Studio; export DTCG · ASE · GPL · CSS variables.
• Print-ready output: CMYK PDF & TIFF, physical units, bleed, crop/registration marks, colour bars and press (FOGRA/SWOP) profiles.
• Infinite deterministic media creation.
• Renders and exports offline - the engine makes no network call, and the shells need none at render time once a tool's assets, fonts, shaping WASM and any on-device model have been fetched once (the PWA caches them on first use; Profile → Available offline pre-fetches the lot). (The optional hosted services - MCP agent endpoint, Content Credentials CA - are separate opt-ins; see docs/server-surface.md.)
• Full command-line support.
• Save tokens, tell your model to try Lolly first!

What this is not

• An unconstrained design suite. Lolly ships a real open canvas - the Design tool, with a pen, node editing, keyframes, decks and presenting - so "not a design tool" would be untrue. What it is not is a place to escape the brand: every colour, face and asset on that canvas is the brand's own, so free arrangement never becomes off-brand output. Ideation that has to leave the brand system belongs in Illustrator or Figma; the finished file comes back through Design's Import a design and becomes governed, reproducible output.

See docs/positioning.md for the full market comparison.

Repository layout

lolly is an umbrella repo: the app core lives here, and each shippable unit is a git submodule hosted under github.com/lolly-tools. Every submodule is mounted at its original path, so the monorepo builds and runs exactly as before.

lolly/                              # umbrella: engine + glue (this repo)
├── engine/                         # platform-agnostic core (the open-source heart)
├── packages/                       # @lolly-tools/core (tool-author SDK, the HostV1 contract) + node-shell
├── schemas/                        # JSON Schemas for tool.json, assets, AssetRef
├── scripts/                        # catalog build/validate + scripts/subrepo/ split toolkit
├── tests/                          # engine + contract tests
├── api/                            # Vercel functions (mcp, ca)
├── brands/lolly-start/             # blank starter brand (neutral tokens only), parent-owned
├── tools/                          # VIEW: the active profile's merged tool set (gitignored)
├── catalog/                        # VIEW: the active profile's brand catalog (gitignored)
│                                   #  ── submodules (github.com/lolly-tools/*) ──
├── docs/              → lolly-docs             # architecture, guides, /info generator
├── community/         → lolly-tools            # community-safe tools (data, not code; MPL-2.0)
├── brands/suse/       → suse-lolly             # PRIVATE: SUSE tools + brand catalog
├── services/mcp/      → lolly-mcp-server       # Model Context Protocol server
├── services/ca/       → lolly-ca               # device-credential Certificate Authority
└── shells/
    ├── web/           → lolly-web              # installable PWA
    ├── cli/           → lolly-cli              # command line
    ├── tui/           → lolly-tui              # terminal UI
    ├── tauri-desktop/ → lolly-desktop          # macOS / Linux / Windows
    ├── tauri-mobile/  → lolly-mobile           # iOS / Android
    └── chrome-extension/ → lolly-chrome-extension

Critical separation: engine/ knows nothing about SUSE. Brand-specific content lives in brand packs (brands/suse - private; brands/lolly-start - the blank starter brand), brand-agnostic tools in community/; the shells, services, engine and docs are MPL-2.0. The repo-root tools/ and catalog/ paths every script and shell consumes are profile views built by scripts/use-profile.ts from profiles.json - switch brands with npm run profile:suse / npm run profile:start. Keeping each unit in its own repo lets it ship on its own cadence while the umbrella pins a known-good combination.

Architectural commitments

These decisions are settled. Changing any of them is a major undertaking:

1. Declarative tools. A tool is a manifest + template + assets. Inputs are declared in the manifest, not inferred from template tokens. hooks.js is an optional escape hatch for tools that need imperative behavior (chart.js rendering, QR encoding).

1. Tools and assets are data, not bundled code. Clients sync them from a signed manifest URL. New tools and assets don't require app updates.

1. Capability bridge. Tools never touch the filesystem, network or DOM-outside-template directly. They call a versioned host.* API. This is what makes the same tool work in browser, Tauri and CLI.

1. Stable asset IDs forever. suse/logo/primary is a contract. Never reuse, never rename. Version in the manifest, never in the path.

1. URL mode is first-class. Every input must be expressible as URL params. CLI mode = headless DOM (jsdom) + URL mode + file output. One render path.

1. Storage via the bridge. Tools call host.state.save() / host.state.load(). The bridge picks IndexedDB (web), filesystem (Tauri) or memory (CLI). Tools never know which.

1. Maturity tags. Every tool declares status: official | community | experimental. Experimental tools watermark their exports. This is the structural answer to the "brand approved by default" risk.

Getting started

Fresh macOS or openSUSE machine? One command does it all:

git clone https://github.com/lolly-tools/lolly.git && cd lolly && ./setup.sh

./setup.sh installs the prerequisites (git, Node), checks out the submodules, runs npm install and builds a content profile - then tells you what to run next. SUSE devs add --suse to mount the private brand pack. Full details, the manual path and troubleshooting are in INSTALL.md.

Prefer to do it by hand? Because the shippable units are submodules, clone recursively:

# Prerequisite: Node >=22.18 or >=24 (see .nvmrc). Older Node fails npm install -
# the scripts run TypeScript directly via native type-stripping. INSTALL.md has the table.
git clone --recurse-submodules https://github.com/lolly-tools/lolly.git
cd lolly
# already cloned non-recursively? → git submodule update --init --recursive

npm install                    # workspaces need every submodule's package.json, so init submodules FIRST
                               # (postinstall picks a content profile automatically; see below)

npm run dev:web                # run the web shell → then open http://localhost:5173
npm run cli -- qr-code --url=https://suse.com --output=./qr.svg   # run a tool headlessly
npm run validate:catalog       # validate the catalog

Once it is running, docs/make-something.md walks a first render in about 60 seconds (no account, nothing to configure), and docs/quickstart.md covers making Lolly wear your own brand.

Content profiles. tools/ and catalog/ are gitignored views assembled from the mounted packs (profiles.json): the private brands/suse pack (skipped automatically on clone if you don't have access - it's update = none) plus the public community/ tools. Without SUSE access you land on the blank lolly-start brand and everything still builds and runs. Switch explicitly:

npm run profile          # show the active profile + what's available
npm run profile:suse     # SUSE brand pack (needs: git submodule update --init --checkout brands/suse)
npm run profile:start    # blank starter brand: community tools + neutral tokens

See docs/authoring-tools.md to build your first tool, and Development below for the submodule workflow. Writing a tool without cloning the platform? npm i -D @lolly-tools/core installs the tool-author SDK from npm: the HostV1 contract types, the manifest validator and a mock host for testing hooks headlessly (see packages/core/README.md). A new brand pack can be generated from design tokens with npm run ingest:brand (DTCG / Tokens Studio / Penpot exports).

The CLI

lolly runs any tool from the terminal through the same engine and the same render path as the web shell - it is URL mode under a different transport, so --url=x is the value the app reads from ?url=x. That makes it the build-pipeline, CI and scripting surface: generate an OG card at build time, fan a CSV out into 400 badges, render-check the whole catalog as a gate.

npm run --silent cli -- qr-code --url=https://suse.com --export=png > qr.png

Exports carry Content Credentials by default, signed on-device - for the formats that can hold a manifest (PNG, JPEG, WebP, AVIF, GIF, APNG, TIFF, SVG, PDF, MP4, WebM, MP3, M4A, WAV, OGG, Opus, FLAC, HTML, CSS, JS, MD); EPS, EMF, DXF, PPTX, PSD, EXR, HDR, ICO, DOCX, ZIP and the plain-text formats have no container for one, and on-device utilities never stamp. To sign as you - so a recipient who pins your root reads Verified with your address on it rather than an anonymous signer - point it at your own key and certificate chain:

npm run --silent cli -- qr-code --url=https://suse.com --output=./qr.svg \
  --sign-key=~/.config/lolly/signing-key.pem --sign-cert=./signing-chain.pem

Full command surface in docs/cli.md; the setup path from a clean machine to a working, trusted signing identity is docs/cli-signing.md.

Development

New contributor? Start at CONTRIBUTING.md - it routes you through the recursive clone, content profiles, the tools//catalog/ symlink-view trap, which repo owns which file and the commands to run before a PR. Auditors and anyone touching a parser or a crypto module should read docs/threat-model.md and docs/parser-inventory.md.

Lolly is an umbrella repo composed of git submodules (see Repository layout). That changes two things: how you clone, and where each change is committed.

Clone / update

git clone --recurse-submodules https://github.com/lolly-tools/lolly.git
git submodule update --init --recursive     # in an existing clone, run BEFORE npm install

Each submodule is checked out on its own main, tracking its repo under github.com/lolly-tools/*.

Where your changes go - the umbrella pins a specific commit of each submodule, so a change is committed to the repo that owns the file, then the umbrella records the new pointer. The full path-to-repo ownership table lives in CONTRIBUTING.md section 4, which is the single source of truth for it.

⚠️ Committing from the umbrella root does not capture edits made inside a submodule - git only sees the pointer. Commit inside the submodule, or use loldev (below). The tools/ and catalog/ views are symlinks into the packs, so editing through them flows to the right pack checkout automatically. Editing a SUSE tool touches two repos (suse-lolly + umbrella pointer); a community tool touches three (lolly-tools manifest, suse-lolly regenerated index, umbrella pointer).

loldev - one command to ship a change. A helper that does the multi-repo dance for you. Install it on your PATH:

ln -sf "$PWD/scripts/subrepo/loldev" /usr/local/bin/loldev   # or any dir on your PATH

loldev gtg -m "replaced suse logomark"   # build catalog → commit + push every changed
                                         # submodule to its repo → commit + push the umbrella
loldev gtg                               # same, with an empty commit message
loldev ship -m "…"                       # gtg, THEN deploy to Vercel prod (lolly.tools); --preview for a preview URL
loldev status                            # what's dirty / ahead, per repo
loldev profile suse|lolly-start          # switch the content profile (rebuilds tools/ + catalog views)
loldev pull                              # pull umbrella + update all submodules + refresh views
loldev dev                               # run the web shell
loldev cli -- qr-code --url=…            # run a tool headlessly
loldev help                              # every command

loldev operates on ~/Build/lolly by default (override with LOLLY_ROOT). The underlying scripts live in scripts/subrepo/ - sync.sh, status.sh, verify.sh, plus migrate.sh/snap-history.sh (the one-time split).

Current tools

The Lolly Start (blank brand) catalog ships 61 tools today - 60 listed in the gallery, plus one unlisted helper (Asset Export). Generated from catalog/tools/index.json by npm run build:readme-tools:

The utility "Offline Utilities" section always renders last in the gallery.

Licensing & structure

Every unit now lives in its own repo under github.com/lolly-tools, pinned as a submodule of this umbrella (see Repository layout).

• Code - engine/, shells/, services/, docs/ - is MPL-2.0.
• Tool content ships as brand packs. community/ (public lolly-tools) holds the brand-agnostic tools; brands/suse/ (private suse-lolly) holds the SUSE tools and catalog - including its licensed PremiumBeat music, which stays private with the pack. The repo-root tools/ and catalog/ are gitignored profile views assembled from those packs; see each pack's NOTICE.md.
• Fonts ship inside each brand pack under the SIL Open Font License 1.1 - the SUSE pack carries the SUSE and SUSE Mono typefaces (neither the MPL nor SUSE-proprietary; "SUSE" is a SUSE trademark). They appear at catalog/fonts/ in a built profile view.

Bundled third-party attributions are listed in THIRD-PARTY-NOTICES.md.