@apisurf/canonui 0.1.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Luka Vidakovic
+
+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.

package/README.md

@@ -0,0 +1,97 @@
+# @apisurf/canonui
+
+The `canonui` command: build and preview the documents that [`canon`](../cli) holds.
+
+```sh
+npm i -g @apisurf/canonui
+canonui ls                     # what is in the database, and what to build
+canonui build retry-guide      # -> ./dist/retry-guide
+canonui serve retry-guide      # build it, then open it in a browser
+canonui open ./public          # serve a folder that is already built
+canonui help
+```
+
+Four commands, none of which writes anything. `canon` is the agent's half of the
+pair — it creates and edits content, one record per command — and this is the
+human's: it opens the same database read-only, says what is in it, and turns a
+document into a folder of static files.
+
+It is usable on its own. `canonui ls` prints the slugs the other commands take, and
+`build` and `serve` resolve the only document themselves when there is one — so
+nothing here sends you to `canon` to find out what to type.
+
+Everything is documented in the command itself — `canonui help`, then
+`canonui help <command>` — and in the [repository README](../../README.md).
+
+## What is in here
+
+Two halves of one package, and the seam between them is a JSON file.
+
+| File             | What it is                                                    |
+| ---------------- | ------------------------------------------------------------- |
+| `src/bin.ts`     | Argument parsing and dispatch. One parser per command         |
+| `src/list.ts`    | `ls`, and the document `build` picks when given none          |
+| `src/db.ts`      | Opening the file `canon` owns, read-only and unmigrated       |
+| `src/build.ts`   | Open the database, reduce a document to a snapshot, render it |
+| `src/serve.ts`   | `serve` — build a document, then hand it to the server        |
+| `src/open.ts`    | `open` — work out which built folder was meant                |
+| `src/http.ts`    | The static file server both of them end at                    |
+| `src/render.ts`  | Spawning Astro with the theme, parameterised by environment   |
+| `src/help.ts`    | Every help page. One screen each                              |
+| `src/howto.ts`   | Worked examples: preview, publish, snapshot                   |
+| `src/format.ts`  | The listing `ls` prints, and its JSON                         |
+| `src/version.ts` | The build's version, and the schema it expects                |
+| `theme/`         | The Astro theme — the only part that renders anything         |
+
+Only `src/` links against SQLite, and only `theme/` knows what HTML is. That is
+what lets `canonui build --snapshot-only` hand the same input to some other
+renderer, and what lets the theme be worked on without a database in reach.
+
+## The theme
+
+One document builds into one page. One layout with three named slots (`head`,
+`aside`, `footer`) and a default behind each, one component per block type, and
+one stylesheet of plain CSS with tokens on `:root`.
+
+The page is two columns: the document — title, description, a copy button, then
+every block in order — and a rail listing its titled blocks and the headings
+inside markdown blocks. There is no framework, and the client-side runtime is
+four small scripts: the wide toggle, the copy button, the rail's scroll
+tracking, and mermaid when the document holds a diagram — bundled into the site
+rather than fetched from a CDN, so it works offline.
+
+| File                           | What it is                                      |
+| ------------------------------ | ----------------------------------------------- |
+| `theme/layouts/Site.astro`     | The shell, and every slot a theme would replace |
+| `theme/components/Block.astro` | One block, drawn according to its type          |
+| `theme/components/Toc.astro`   | The contents rail                               |
+| `theme/components/Copy.astro`  | The button that copies the document as markdown |
+| `theme/pages/index.astro`      | The document, at `/`                            |
+| `theme/styles/theme.css`       | The whole of the styling                        |
+| `theme/lib/snapshot.ts`        | The snapshot, read once at build time           |
+
+### The markdown twin
+
+`/index.md` is written by the command rather than the theme, with
+`bundleDocument` — the same function behind `canon cat`, so what a reader copies
+out of the site is byte for byte `canon cat --toc --no-meta`. The theme builds on
+a machine that has no workspace to resolve that function from; the command
+already carries it, which is what keeps the site and the CLI one renderer. The
+copy button fetches it rather than embedding it, so the button wants the site
+served rather than opened off the disk, where `fetch` has no origin to work
+from; everything else on the page works either way.
+
+The theme sits under `theme/` rather than Astro's default `src/`, which this
+package uses for the command itself. `astro.config.mjs` points `srcDir` at it.
+
+## Build parameters
+
+`src/render.ts` passes these to Astro as environment variables, so the package
+stays immutable at build time and two builds cannot race over a config file.
+
+| Variable          | What it sets                                    |
+| ----------------- | ----------------------------------------------- |
+| `CANON_SITE_DATA` | Path to the snapshot JSON. Required             |
+| `CANON_OUT_DIR`   | Absolute path to write the site to. Required    |
+| `CANON_BASE`      | Sub-path the site is served under, e.g. `/docs` |
+| `CANON_SITE_URL`  | Canonical origin, for absolute URLs             |

package/astro.config.mjs

@@ -0,0 +1,30 @@
+import { defineConfig } from "astro/config";
+
+/**
+ * One Astro project, many sites.
+ *
+ * The theme is fixed; what changes per build is the snapshot it reads and where
+ * the output lands, and both arrive as environment variables rather than as a
+ * generated config file. That keeps this package immutable at build time — two
+ * `canonui build` runs for different documents cannot race over a file in here.
+ *
+ *   CANON_SITE_DATA   path to the document snapshot JSON (required)
+ *   CANON_OUT_DIR     absolute path to write the site to (required)
+ *   CANON_BASE        sub-path the site will be served under, e.g. /docs
+ *   CANON_SITE_URL    canonical origin, for absolute URLs in the output
+ *
+ * The theme sits under theme/ rather than the default src/, which this package
+ * uses for the canonui command itself. Astro's usual output directory is likewise
+ * given up: dist/ holds the compiled CLI, so a build that somehow arrived here
+ * without CANON_OUT_DIR must land somewhere it cannot overwrite the binary.
+ */
+export default defineConfig({
+  srcDir: "./theme",
+  outDir: process.env.CANON_OUT_DIR ?? "./.astro-out",
+  ...(process.env.CANON_SITE_URL ? { site: process.env.CANON_SITE_URL } : {}),
+  ...(process.env.CANON_BASE ? { base: process.env.CANON_BASE } : {}),
+  build: { format: "directory" },
+  // The output is opened over a plain static server with no build step of its
+  // own, so nothing may depend on a dev-time transform being available.
+  devToolbar: { enabled: false },
+});