Update kjol website with C documentation

go/cmd/kjol-web/frontend/src/layers.ts

@@ -1,14 +1,22 @@
-// The layers of kjol, as data.
+// What kjøl is made of, as data.
 //
-// This is the JS mirror of app/layers.go on the Go/WASM side. The site has two
-// front-ends built by two completely different pipelines, and the Layers menu has
-// to be identical in both — so it is a LIST in each, not markup, and the two lists
-// are the only thing that has to be kept in step.
+// There are two kinds of thing here, and conflating them was the mistake this file used
+// to make — one flat list called "the layers", holding both.
 //
-// (A shared source would be better than a mirrored one. There isn't one: the Go
-// side compiles to WebAssembly and the JS side is bundled by esbuild, and nothing
-// is upstream of both. Keeping it to a flat array of plain data is what makes the
-// duplication survivable — you can diff the two by eye.)
+//   LAYERS       are LANGUAGES. What kjøl is written in, and what it gives you in each:
+//                the Go base, the TypeScript kit, the C base, the Jai modules. A layer is
+//                a directory of code you can use on its own.
+//
+//   COMPOSITIONS are FRAMEWORKS. What you get when the layers are assembled into
+//                something that does a job — the two web engines. A composition is not
+//                another language; it is a use of them.
+//
+// Kjøl Wasm Web is Go, all the way down. Kjøl JS Web is TypeScript compiled by a Go
+// toolchain — two layers, one framework. Listing that beside "C" as though they were the
+// same kind of noun told the reader nothing about either.
+//
+// This is the JS mirror of app/layers.go. The ids, the order and the taglines match; only
+// the ICONS diverge, and they have to — see below.
 
 export interface Layer {
     name: string;
@@ -20,7 +28,7 @@ export interface Layer {
      * The ONE field that does not match app/layers.go, and cannot: the two kits have
      * different icon sets. This side names FontAwesome; the Go side names webui's own
      * hand-drawn registry, which has no FontAwesome in it at all. Where the two have no
-     * glyph in common the names diverge (here `table-columns`, there `squares`).
+     * glyph in common the names diverge.
      *
      * Both sides fail loudly rather than quietly — a name neither registry knows renders
      * an empty box, and app/icons_test.go fails the build over it.
@@ -28,45 +36,59 @@ export interface Layer {
     icon: string;
 }
 
-export const LAYERS: Layer[] = [
+/** Languages: what kjøl is written in. */
+export const LANGUAGES: Layer[] = [
     {
-        name: "Kjol Go",
+        name: "Go",
         href: "/go",
-        tagline: "The server base: config, database, logging, HTTP, mail, validation.",
+        tagline: "The base: config, database, logging, HTTP, mail, validation — and both web engines.",
         live: false,
         icon: "server",
     },
     {
-        name: "Kjol Wasm Web",
-        href: "/wasm",
-        tagline: "Web interfaces written in Go, compiled to WebAssembly. SSR + hydration, no JS build.",
-        live: true,
+        name: "TypeScript",
+        href: "/ts",
+        tagline: "The Solid component kit, the vendored runtime, and the generic scaffolding apps import as @kjol/*.",
+        live: false,
         icon: "code",
     },
     {
-        name: "Kjol JS Web",
-        href: "/js",
-        tagline: "The Solid component kit, bundled by a Go toolchain: TSX → Solid → esbuild, Tailwind in Go.",
-        live: true,
-        icon: "table-columns",
-    },
-    {
-        name: "Kjol C",
+        name: "C",
         href: "/c",
-        tagline: "Arena allocator, strings, math, lexer, platform layer.",
-        live: false,
+        tagline: "Arena allocator, counted strings, math, a lexer, a platform layer — and a build system that is a C file.",
+        live: true,
         icon: "bolt",
     },
     {
-        name: "Kjol Jai",
+        name: "Jai",
         href: "/jai",
-        tagline: "Console rendering module. Early.",
+        tagline: "Console rendering. Early.",
         live: false,
         icon: "cube",
     },
 ];
 
-/** The layer the current path belongs to, or undefined on the front page. */
+/** Compositions: what the languages are assembled into. */
+export const COMPOSITIONS: Layer[] = [
+    {
+        name: "Kjøl Wasm Web",
+        href: "/wasm",
+        tagline: "Web interfaces written in Go, compiled to WebAssembly. SSR + hydration, and no JavaScript build at all.",
+        live: true,
+        icon: "code",
+    },
+    {
+        name: "Kjøl JS Web",
+        href: "/js",
+        tagline: "The Solid component kit, bundled by a Go toolchain: TSX → Solid → esbuild, Tailwind in Go.",
+        live: true,
+        icon: "table-columns",
+    },
+];
+
+/** The layer or composition the current path belongs to, or undefined on the front page. */
 export function currentLayer(path: string): Layer | undefined {
-    return LAYERS.find((l) => path === l.href || path.startsWith(l.href + "/"));
+    return [...COMPOSITIONS, ...LANGUAGES].find(
+        (l) => path === l.href || path.startsWith(l.href + "/"),
+    );
 }