@moku-labs/web 0.3.0 → 0.3.1

package/dist/index.cjs

@@ -851,7 +851,27 @@ const coreConfig = (0, _moku_labs_core.createCoreConfig)("web", {
 		env: { providers: [dotenv(), processEnv()] }
 	}
 });
-const { createPlugin: createPlugin$1, createCore } = coreConfig;
+/**
+* Create a custom plugin bound to this framework's `Config`/`Events` and the core
+* plugin APIs (`log`, `env`). Plugin types are fully inferred from the spec
+* object — never write them explicitly. This is the binding every built-in
+* plugin is wired with, and the one consumer plugins should use too.
+*
+* @example
+* ```ts
+* const analytics = createPlugin("analytics", {
+*   config: { writeKey: "" },
+*   api: (ctx) => ({ track: (event: string) => ctx.log.info("analytics:track", { event }) })
+* });
+* ```
+*/
+const createPlugin$1 = coreConfig.createPlugin;
+/**
+* Step 2 of the factory chain — captures the framework's default plugin set and
+* returns the consumer entry points ({@link createApp} + a re-exported
+* `createPlugin`). Wired once in `src/index.ts`; consumers don't call it directly.
+*/
+const createCore = coreConfig.createCore;
 //#endregion
 //#region src/plugins/i18n/api.ts
 /** Error prefix for all i18n lifecycle failures. */
@@ -979,6 +999,25 @@ function createI18nApi(ctx) {
 		}
 	};
 }
+/**
+* Internationalization plugin — locale registry plus a flat translation helper
+* with default-locale fallback. Pure config-as-data (no state or events);
+* consumed read-only by content, router, head, and build.
+*
+* @example Register locales and translations
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     i18n: {
+*       locales: ["en", "uk"],
+*       defaultLocale: "en",
+*       localeNames: { en: "English", uk: "Українська" },
+*       translations: { uk: { "nav.home": "Головна" } }
+*     }
+*   }
+* });
+* ```
+*/
 const i18nPlugin = createPlugin$1("i18n", {
 	config: {
 		locales: ["en"],
@@ -1774,6 +1813,26 @@ function validateContentConfig(config) {
 * and `content:invalidated`.
 * @see README.md
 */
+/**
+* Content plugin — Markdown pipeline: discovers files, parses frontmatter, renders
+* to sanitized HTML (rehype-sanitize unless `trustedContent`), and exposes a
+* locale-keyed Article model. Depends on i18n; emits `content:ready` and
+* `content:invalidated`.
+*
+* @example Point at a content directory and pick a Shiki theme
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     content: {
+*       contentDir: "./content",
+*       shikiTheme: "github-dark",
+*       defaultAuthor: "Ada Lovelace"
+*       // trustedContent: true // ONLY for fully author-controlled Markdown — disables sanitize
+*     }
+*   }
+* });
+* ```
+*/
 const contentPlugin = createPlugin$1("content", {
 	depends: [i18nPlugin],
 	events: contentEvents,
@@ -1937,6 +1996,25 @@ function createSiteApi(ctx) {
 		}
 	};
 }
+/**
+* Site plugin — holds global, frozen site metadata (name, url, author,
+* description) and builds canonical URLs. Consumed by router, head, and build.
+* `name` and `url` must be non-empty (validated at `onInit`).
+*
+* @example Set your site identity
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     site: {
+*       name: "My Blog",
+*       url: "https://blog.dev",
+*       author: "Ada Lovelace",
+*       description: "Notes on computing"
+*     }
+*   }
+* });
+* ```
+*/
 const sitePlugin = createPlugin$1("site", {
 	config: {
 		name: "",
@@ -2566,6 +2644,26 @@ function defineRoutes(routes) {
 function createState$4(_ctx) {
 	return { table: null };
 }
+/**
+* Router plugin — typed, named route definitions with locale-aware URL generation
+* and matching. Author routes with {@link route} + {@link defineRoutes}. Depends
+* on site (base URL) and i18n (locales).
+*
+* @example Define routes and choose a render mode
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     router: {
+*       routes: defineRoutes({
+*         home: route("/"),
+*         article: route("/blog/{slug}/")
+*       }),
+*       mode: "hybrid" // "ssg" | "spa" | "hybrid" (default)
+*     }
+*   }
+* });
+* ```
+*/
 const routerPlugin = createPlugin$1("router", {
 	depends: [sitePlugin, i18nPlugin],
 	helpers: {
@@ -3079,6 +3177,25 @@ function createState$3(_ctx) {
 * @file head — Standard Plugin wiring harness (logic in primitives/compose/api/config).
 * @see README.md
 */
+/**
+* Head plugin — composes per-route `<head>` metadata (title template, Open Graph,
+* Twitter cards, canonical, hreflang). Use the re-exported SEO primitives
+* ({@link meta}, {@link og}, {@link twitter}, …) inside a route's `.head()`.
+* Depends on site, i18n, and router.
+*
+* @example Set global head defaults
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     head: {
+*       titleTemplate: "%s — My Blog",
+*       twitterCard: "summary_large_image",
+*       twitterHandle: "@moku_labs"
+*     }
+*   }
+* });
+* ```
+*/
 const headPlugin = createPlugin$1("head", {
 	depends: [
 		sitePlugin,
@@ -4086,6 +4203,27 @@ function createState$2(ctx) {
 * @file build — Complex plugin: SSG orchestrator (wiring harness only).
 * @see README.md
 */
+/**
+* Build plugin — the static-site-generation orchestrator. Renders every route to
+* `outDir`, and optionally emits feeds, a sitemap, optimized images, and OG
+* images. Depends on site, i18n, content, router, and head; emits `build:phase`.
+*
+* @example Configure the production build
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     build: {
+*       outDir: "dist",
+*       minify: true,
+*       feeds: true,
+*       sitemap: true,
+*       images: true,
+*       ogImage: false // or an object to enable + configure OG-image generation
+*     }
+*   }
+* });
+* ```
+*/
 const buildPlugin = createPlugin$1("build", {
 	depends: [
 		sitePlugin,
@@ -4885,6 +5023,24 @@ function createState$1(_ctx) {
 * Depends: site. Emits: deploy:complete.
 * @see README.md
 */
+/**
+* Deploy plugin — ships the built `outDir` to Cloudflare Pages via the injectable
+* wrangler subprocess, with entropy-gated secret scrubbing of logged output.
+* Depends on site; emits `deploy:complete`.
+*
+* @example Configure the deploy target
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     deploy: {
+*       target: "cloudflare-pages",
+*       outDir: "dist",
+*       productionBranch: "main"
+*     }
+*   }
+* });
+* ```
+*/
 const deployPlugin = createPlugin$1("deploy", {
 	config: defaultConfig,
 	depends: [sitePlugin],
@@ -5857,6 +6013,26 @@ function disposeSpa() {
 * Emits: spa:navigate, spa:navigated, spa:component-mount, spa:component-unmount.
 * @see README.md
 */
+/**
+* SPA plugin — progressive client-side navigation layered over the static site:
+* swaps a page region on navigation, with an optional progress bar and View
+* Transitions. Register interactive islands with {@link createComponent}. Depends
+* on router and head; emits `spa:navigate`, `spa:navigated`, `spa:component-mount`,
+* and `spa:component-unmount`.
+*
+* @example Enable view transitions and a custom swap region
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     spa: {
+*       swapSelector: "main > section",
+*       viewTransitions: true,
+*       progressBar: true
+*     }
+*   }
+* });
+* ```
+*/
 const spaPlugin = createPlugin$1("spa", {
 	depends: [routerPlugin, headPlugin],
 	config: defaultSpaConfig,
@@ -5891,7 +6067,13 @@ var types_exports$5 = /* @__PURE__ */ __exportAll({});
 //#endregion
 //#region src/plugins/router/types.ts
 var types_exports$6 = /* @__PURE__ */ __exportAll({});
-const { createApp, createPlugin } = createCore(coreConfig, {
+//#endregion
+//#region src/index.ts
+/**
+* @file `@moku-labs/web` — a Moku Layer-2 content static-site + SPA framework.
+* @see README.md
+*/
+const framework = createCore(coreConfig, {
 	plugins: [
 		sitePlugin,
 		i18nPlugin,
@@ -5904,6 +6086,46 @@ const { createApp, createPlugin } = createCore(coreConfig, {
 	],
 	pluginConfigs: {}
 });
+/**
+* Create and initialize a `@moku-labs/web` application — the Layer-3 entry point.
+* Your overrides are merged over the framework defaults through the 4-level config
+* cascade, every plugin's lifecycle runs, and a fully-typed, frozen app is returned.
+*
+* @param options - Optional configuration:
+*  - `pluginConfigs` — per-plugin overrides, keyed by plugin name
+*    (`site`, `i18n`, `router`, `content`, `head`, `build`, `spa`, `deploy`, `env`).
+*  - `config` — global framework config (e.g. `{ mode: "development" }`).
+*  - `plugins` — extra consumer plugins, merged into the app and its return type.
+*  - `onReady` / `onError` / `onStart` / `onStop` — lifecycle callbacks.
+* @returns The initialized app: `start()`, `stop()`, every plugin's API, and `log`.
+* @example
+* ```ts
+* const app = createApp({
+*   pluginConfigs: {
+*     site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes" },
+*     router: { routes: defineRoutes({ home: route("/"), post: route("/blog/{slug}/") }) }
+*   }
+* });
+* await app.start();
+* ```
+*/
+const createApp = framework.createApp;
+/**
+* Create a custom plugin bound to this framework's `Config`/`Events` and core
+* APIs. Plugin types are inferred from the spec object — never written explicitly.
+* Pass the result to {@link createApp} via `plugins`.
+*
+* @example
+* ```ts
+* const analytics = createPlugin("analytics", {
+*   config: { writeKey: "" },
+*   api: (ctx) => ({ track: (event: string) => ctx.log.info("analytics:track", { event }) })
+* });
+*
+* const app = createApp({ plugins: [analytics] });
+* ```
+*/
+const createPlugin = framework.createPlugin;
 //#endregion
 Object.defineProperty(exports, "Build", {
 	enumerable: true,