Crafts

A craft is a small application that lives inside a LogiSheets workbook.

You write the logic once, and it reaches three places: a UI in the browser, a headless runtime on Node, and the AI assistant. Same code, three ways in.

Crafts work on blocks — that is how one craft can read what another one wrote without the two colliding.

What a craft gives you

A spreadsheet is generic. Your work isn't. A craft is how you teach LogiSheets your domain: you write the specific logic your business needs — a pricing model, a data validator, a what-if analysis, an inventory simulator, a custom input tool — and it becomes a first-class feature of the sheet.

• Build for a concrete workflow. Instead of forcing users to remember which cells and formulas to touch, give them a button, a form, or a game board that does the thing — correctly, every time.
• Your logic, not ours. A craft is your code operating on the workbook through its public API. You decide what it does; the platform provides the sheet, the UI surface, the persistence, and the AI.
• Convenient for the people using it. The craft encodes the know-how, so the end user just clicks (or asks the AI) — no spreadsheet expertise required.

The crafts already in the repo hint at the range: what-if-calculator (preview changes before committing), markdown-table-extractor (turn a selection into a table), and sudoku / minesweeper / fuse-beads (interactive boards). Each is a small app for one job.

One logic, three faces

The reason a craft is worth writing once is that a single implementation reaches every surface. You write the logic (plain functions that operate on the workbook), then add a thin interface for each surface you want:

• an index.html to give it a UI in the browser,
• a few conventional functions to run it headless in a runtime,
• some JSDoc to expose it to the AI assistant.

None of these re-implement the logic — they're thin adapters over the same core.

Each face is optional — implement only the ones your craft needs. A game is UI-only; most crafts pick two or three. One rule: a craft needs at least one of index.html or tools.ts, so a runtime face cannot stand on its own.

• Browser — a standalone package loaded in a same-origin <iframe> in the craft panel. The host injects capabilities onto the craft's window (read/write the sheet, listen to canvas input, persist state, …), and your index.html is the UI that calls your logic.
• Runtime — the same logic can run without any UI: conventional functions the platform calls headlessly, e.g. to validate an edit before it commits, or to run in Node or the collaboration server.
• AI (Watson) — annotate your functions with JSDoc and the craftsmith CLI turns them into a capability manifest the built-in AI assistant uses to discover your craft and call it. The manifest is generated from your code, so it can never drift.

One implementation, no drift

The point of the thin-interface design: the exact function your button calls is the function the runtime calls is the function Watson calls. There is no separate "tool layer" and no duplicated logic to keep in sync — a craft is the logic, and the browser / runtime / AI are just ways to reach it.

Get started

➡️ Putting it together — how crafts and blocks combine, and why an agent is what makes those combinations actually get used.

➡️ Write your own craft — scaffold with the craftsmith CLI, then the guide covers the host API, the common patterns, the gotchas, and how to expose your craft's functions as AI tools.

npx craftsmith new my-craft
cd my-craft && npm install
npx craftsmith check .     # validate the contract
npx craftsmith build .     # compile → dist/