@moku-labs/web 0.1.0-alpha.4 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Alex Kucherenko
+Copyright (c) 2026 moku-labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,73 +1,86 @@
 # @moku-labs/web
 
-Layer-2 static-site framework built on [`@moku-labs/core`](https://github.com/moku-labs/core). Plugin-composed, Bun-native, with built-in LLM-verifiable test trace and universal env injection.
+**A content static-site generator + SPA web framework for TypeScript.** Built on
+[@moku-labs/core](https://github.com/moku-labs/core) — three layers of isolation, plugins all the
+way down, types doing the heavy lifting.
 
-**Status:** Alpha. Skeleton phase — see `.planning/` for specs.
-
-## Quick Start
-
-```bash
+```
 bun add @moku-labs/web
 ```
 
-```ts
-import { createApp, route, meta, og, canonical } from '@moku-labs/web'
+> Status: `0.1.0` — early. The API is settling but not yet frozen.
 
-const app = createApp({
-  mode: 'production',
-  site: { name: 'My Blog', url: 'https://example.com', author: 'Jane Doe', description: 'Personal blog' },
-  i18n: { locales: ['en'] as const, defaultLocale: 'en', localeNames: { en: 'English' } },
-  contentDir: '/abs/path/to/content',
-  routes: {
-    home: route('/').render(() => <HomePage />),
-  },
-})
-
-await app.build.run()
-```
+---
 
-## Architecture
+## What it is
 
-- **10 domain-grouped plugins** (`log`, `env`, `site`, `i18n`, `content`, `router`, `head`, `build`, `spa`, `deploy`) wired via `@moku-labs/core` micro-kernel
-- **Bun-native bundler** (no Vite subprocess)
-- **Generic-preserving `createApp` wrapper** projects flat config → `pluginConfigs`
-- **Dev mode** lives in `bin/moku.ts dev` (NOT a plugin)
-- **Cloudflare Pages deploy** via the `deploy` plugin and `moku deploy` CLI (see `src/plugins/deploy/README.md`)
+`@moku-labs/web` composes a small set of focused plugins into one framework: author Markdown
+content, declare type-safe routes, generate SEO-complete HTML + feeds + sitemap at build time, and
+optionally hydrate islands and deploy to Cloudflare Pages.
 
-## Writing custom plugins
+The consumer surface is one `createApp` call plus a typed routing DSL — you never import from
+`@moku-labs/core` directly.
 
-Consumer apps can extend the framework with their own plugins using the framework-bound `createPlugin` (NOT the raw one from `@moku-labs/core`):
+## Quick start
 
 ```ts
-import { createApp, createPlugin, i18n, type Site } from '@moku-labs/web'
-
-const analytics = createPlugin('analytics', {
-  depends: [i18n],
-  config: { trackingId: '' },
-  createState: () => ({ events: [] as string[] }),
-  api: (ctx) => ({ track: (name: string) => { ctx.state.events.push(name) } }),
-})
-
-const siteConfig: Site.SiteConfig = {
-  name: 'My Blog',
-  url: 'https://example.com',
-  author: 'Jane Doe',
-  description: 'Personal blog',
-}
+import { createApp, defineRoutes, route } from "@moku-labs/web";
+
+const routes = defineRoutes({
+  home: route("/")
+    .render(() => <h1>My Blog</h1>)
+    .head(() => ({ title: "My Blog" })),
+  article: route("/{lang:?}/{slug}/")
+    .generate((locale) => listSlugs(locale).map((slug) => ({ lang: locale, slug })))
+    .load(({ slug }, locale) => loadArticle(slug, locale)) // widens ctx.data
+    .render((ctx) => <Article article={ctx.data} />)
+    .head((ctx) => ({ title: ctx.data.title, description: ctx.data.description }))
+});
+
+const app = createApp({
+  config: { mode: "production" },
+  pluginConfigs: {
+    site: { name: "My Blog", url: "https://blog.dev", author: "Me", description: "A personal blog." },
+    i18n: { locales: ["en", "uk"], defaultLocale: "en" },
+    content: { contentDir: "./content" },
+    router: { routes, mode: "ssg" },
+    head: { titleTemplate: "%s — My Blog" },
+    build: { outDir: "dist", feeds: true, sitemap: true }
+  }
+});
+
+await app.build.run(); // → static site in dist/ (HTML, feed.xml, sitemap.xml)
 ```
 
-All 10 plugin instances (`log, env, site, i18n, content, router, head, build, spa, deploy`) and their namespaced config types (`Log, Env, Site, I18n, Content, Router, Head, Build, Spa, Deploy`) are exported from the main entry — use them for `ctx.require(...)` access and for typing `pluginConfigs` overrides.
+Content lives on disk as `content/{slug}/{locale}.md` with YAML frontmatter
+(`title`, `date`, `description`, `tags`, `language`, optional `draft`/`author`). Drafts are excluded
+from production builds.
 
-## Test helpers (`@moku-labs/web/test`)
+## Plugins
 
-Framework-aware test factories for isolating plugin behavior in unit tests:
+| Plugin | Responsibility |
+|---|---|
+| `site` | Site identity (name, URL, author) + canonical URL helper |
+| `i18n` | Locales, default-locale fallback, translations, hreflang/ogLocale maps |
+| `router` | Type-safe route DSL (`route`/`defineRoutes`), matching, URL/file derivation |
+| `content` | Markdown pipeline → sanitized HTML, frontmatter, reading time, locale model |
+| `head` | SEO `<head>` composition: title template, canonical, OG/Twitter, JSON-LD, hreflang |
+| `build` | SSG orchestrator: pages, feeds (RSS/Atom/JSON), sitemap, OG images |
+| `spa` | Client runtime: island hydration + intercepted navigation |
+| `deploy` | Cloudflare Pages: `wrangler.jsonc` scaffolding + deploy |
+| `log`, `env` | Core plugins: structured logging + validated environment access |
 
-```ts
-import { createTestApp, createTestLog, createTestEnv } from '@moku-labs/web/test'
-```
+SEO primitives are exported for route `.head()` handlers: `meta`, `og`, `twitter`, `jsonLd`,
+`canonical`, `hreflang`, `feedLink`, `buildArticleHead`.
 
-Each factory returns a FRESH instance per call — never a module-level singleton — safe for parallel vitest workers.
+## Scripts
+
+```
+bun run build     # build with tsdown
+bun run test      # vitest (unit + integration)
+bun run lint      # biome + eslint
+```
 
 ## License
 
-MIT
+MIT © moku-labs