@moku-labs/web 0.2.0 → 0.3.1

package/dist/index.d.cts

@@ -1,7 +1,6 @@
-import * as _moku_labs_core0 from "@moku-labs/core";
-import { EmitFn } from "@moku-labs/core";
 import { ComponentChildren, VNode } from "preact";
 import { Pluggable, Processor } from "unified";
+import { EmitFn } from "@moku-labs/core";
 
 //#region \0rolldown/runtime.js
 declare namespace types_d_exports$5 {
@@ -313,7 +312,7 @@ type EnvApi = {
  * createApp({ pluginConfigs: { env: { schema: { PUBLIC_API_URL: { public: true } } } } });
  * ```
  */
-declare const envPlugin: _moku_labs_core0.CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>;
+declare const envPlugin: import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>;
 //#endregion
 //#region src/config.d.ts
 /**
@@ -1798,7 +1797,25 @@ type Api = {
  * Depends: site. Emits: deploy:complete.
  * @see README.md
  */
-declare const deployPlugin: _moku_labs_core0.PluginInstance<"deploy", Config, State, Api, {
+/**
+ * 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"
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", Config, State, Api, {
   "deploy:complete": {
     url: string;
     deploymentId: string;
@@ -1808,7 +1825,28 @@ declare const deployPlugin: _moku_labs_core0.PluginInstance<"deploy", Config, St
 }> & Record<never, never>;
 //#endregion
 //#region src/plugins/build/index.d.ts
-declare const buildPlugin: _moku_labs_core0.PluginInstance<"build", Config$1, State$1, Api$1, {
+/**
+ * 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
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Config$1, State$1, Api$1, {
   "build:phase": {
     phase: PhaseName;
     status: "start" | "done";
@@ -1822,7 +1860,27 @@ declare const buildPlugin: _moku_labs_core0.PluginInstance<"build", Config$1, St
 }> & Record<never, never>;
 //#endregion
 //#region src/plugins/content/index.d.ts
-declare const contentPlugin: _moku_labs_core0.PluginInstance<"content", Config$3, State$3, Api$3, {
+/**
+ * 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
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content", Config$3, State$3, Api$3, {
   "content:ready": {
     locales: readonly string[];
     articleCount: number;
@@ -1911,7 +1969,26 @@ declare function feedLink(title: string, url: string, type?: string): HeadElemen
 declare function buildArticleHead(articleMeta: ArticleMeta, canonicalUrl: string): HeadElement[];
 //#endregion
 //#region src/plugins/head/index.d.ts
-declare const headPlugin: _moku_labs_core0.PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
+/**
+ * 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"
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
   meta: typeof meta;
   og: typeof og;
   twitter: typeof twitter;
@@ -1923,7 +2000,26 @@ declare const headPlugin: _moku_labs_core0.PluginInstance<"head", Config$2, Stat
 };
 //#endregion
 //#region src/plugins/i18n/index.d.ts
-declare const i18nPlugin: _moku_labs_core0.PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>;
+/**
+ * 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": "Головна" } }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/log/index.d.ts
 /**
@@ -1933,7 +2029,7 @@ declare const i18nPlugin: _moku_labs_core0.PluginInstance<"i18n", Config$5, Reco
  *
  * @see README.md
  */
-declare const logPlugin: _moku_labs_core0.CorePluginInstance<"log", LogConfig, LogState, LogApi>;
+declare const logPlugin: import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>;
 //#endregion
 //#region src/plugins/router/builders/route-builder.d.ts
 /**
@@ -1968,16 +2064,75 @@ declare function route<P extends string>(pattern: P): RouteBuilder<RouteState<P>
 declare function defineRoutes<T extends RouteMap>(routes: T): T;
 //#endregion
 //#region src/plugins/router/index.d.ts
-declare const routerPlugin: _moku_labs_core0.PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+/**
+ * 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)
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const routerPlugin: import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
   route: typeof route;
   defineRoutes: typeof defineRoutes;
 };
 //#endregion
 //#region src/plugins/site/index.d.ts
-declare const sitePlugin: _moku_labs_core0.PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
+/**
+ * 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"
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
 //#endregion
 //#region src/plugins/spa/index.d.ts
-declare const spaPlugin: _moku_labs_core0.PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
+/**
+ * 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
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const spaPlugin: import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
   "spa:navigate": {
     from: string;
     to: string;
@@ -1996,114 +2151,153 @@ declare const spaPlugin: _moku_labs_core0.PluginInstance<"spa", SpaConfig, SpaSt
 }> & Record<never, never>;
 //#endregion
 //#region src/index.d.ts
-declare const createApp: <const ExtraPlugins extends readonly _moku_labs_core0.AnyPluginInstance[] = readonly []>(options?: _moku_labs_core0.CreateAppOptions<Config$7, Events, (_moku_labs_core0.PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
-    route: typeof route;
-    defineRoutes: typeof defineRoutes;
-  }) | (_moku_labs_core0.PluginInstance<"content", Config$3, State$3, Api$3, {
-    "content:ready": {
-      locales: readonly string[];
-      articleCount: number;
-    };
-    "content:invalidated": {
-      paths: readonly string[];
-    };
-  }> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
-    meta: typeof meta;
-    og: typeof og;
-    twitter: typeof twitter;
-    jsonLd: typeof jsonLd;
-    canonical: typeof canonical;
-    hreflang: typeof hreflang;
-    feedLink: typeof feedLink;
-    buildArticleHead: typeof buildArticleHead;
-  }) | (_moku_labs_core0.PluginInstance<"build", Config$1, State$1, Api$1, {
-    "build:phase": {
-      phase: PhaseName;
-      status: "start" | "done";
-      durationMs?: number;
-    };
-    "build:complete": {
-      outDir: string;
-      pageCount: number;
-      durationMs: number;
-    };
-  }> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
-    "spa:navigate": {
-      from: string;
-      to: string;
-    };
-    "spa:navigated": {
-      url: string;
-    };
-    "spa:component-mount": {
-      name: string;
-      el: Element;
-    };
-    "spa:component-unmount": {
-      name: string;
-      el: Element;
-    };
-  }> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"deploy", Config, State, Api, {
-    "deploy:complete": {
-      url: string;
-      deploymentId: string;
-      branch: string;
-      durationMs: number;
-    };
-  }> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], _moku_labs_core0.CoreApisFromTuple<[_moku_labs_core0.CorePluginInstance<"log", LogConfig, LogState, LogApi>, _moku_labs_core0.CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>> | undefined) => _moku_labs_core0.App<Config$7, Events, (_moku_labs_core0.PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
-    route: typeof route;
-    defineRoutes: typeof defineRoutes;
-  }) | (_moku_labs_core0.PluginInstance<"content", Config$3, State$3, Api$3, {
-    "content:ready": {
-      locales: readonly string[];
-      articleCount: number;
-    };
-    "content:invalidated": {
-      paths: readonly string[];
-    };
-  }> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
-    meta: typeof meta;
-    og: typeof og;
-    twitter: typeof twitter;
-    jsonLd: typeof jsonLd;
-    canonical: typeof canonical;
-    hreflang: typeof hreflang;
-    feedLink: typeof feedLink;
-    buildArticleHead: typeof buildArticleHead;
-  }) | (_moku_labs_core0.PluginInstance<"build", Config$1, State$1, Api$1, {
-    "build:phase": {
-      phase: PhaseName;
-      status: "start" | "done";
-      durationMs?: number;
-    };
-    "build:complete": {
-      outDir: string;
-      pageCount: number;
-      durationMs: number;
-    };
-  }> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
-    "spa:navigate": {
-      from: string;
-      to: string;
-    };
-    "spa:navigated": {
-      url: string;
-    };
-    "spa:component-mount": {
-      name: string;
-      el: Element;
-    };
-    "spa:component-unmount": {
-      name: string;
-      el: Element;
-    };
-  }> & Record<never, never>) | (_moku_labs_core0.PluginInstance<"deploy", Config, State, Api, {
-    "deploy:complete": {
-      url: string;
-      deploymentId: string;
-      branch: string;
-      durationMs: number;
-    };
-  }> & Record<never, never>) | ExtraPlugins[number], _moku_labs_core0.CoreApisFromTuple<[_moku_labs_core0.CorePluginInstance<"log", LogConfig, LogState, LogApi>, _moku_labs_core0.CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>, createPlugin: _moku_labs_core0.BoundCreatePluginFunction<Config$7, Events, _moku_labs_core0.CoreApisFromTuple<[_moku_labs_core0.CorePluginInstance<"log", LogConfig, LogState, LogApi>, _moku_labs_core0.CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
+/**
+ * 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();
+ * ```
+ */
+declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<Config$7, Events, (import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+  route: typeof route;
+  defineRoutes: typeof defineRoutes;
+}) | (import("@moku-labs/core").PluginInstance<"content", Config$3, State$3, Api$3, {
+  "content:ready": {
+    locales: readonly string[];
+    articleCount: number;
+  };
+  "content:invalidated": {
+    paths: readonly string[];
+  };
+}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
+  meta: typeof meta;
+  og: typeof og;
+  twitter: typeof twitter;
+  jsonLd: typeof jsonLd;
+  canonical: typeof canonical;
+  hreflang: typeof hreflang;
+  feedLink: typeof feedLink;
+  buildArticleHead: typeof buildArticleHead;
+}) | (import("@moku-labs/core").PluginInstance<"build", Config$1, State$1, Api$1, {
+  "build:phase": {
+    phase: PhaseName;
+    status: "start" | "done";
+    durationMs?: number;
+  };
+  "build:complete": {
+    outDir: string;
+    pageCount: number;
+    durationMs: number;
+  };
+}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
+  "spa:navigate": {
+    from: string;
+    to: string;
+  };
+  "spa:navigated": {
+    url: string;
+  };
+  "spa:component-mount": {
+    name: string;
+    el: Element;
+  };
+  "spa:component-unmount": {
+    name: string;
+    el: Element;
+  };
+}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"deploy", Config, State, Api, {
+  "deploy:complete": {
+    url: string;
+    deploymentId: string;
+    branch: string;
+    durationMs: number;
+  };
+}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$7, Events, (import("@moku-labs/core").PluginInstance<"site", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$5, Record<string, never>, Api$5, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+  route: typeof route;
+  defineRoutes: typeof defineRoutes;
+}) | (import("@moku-labs/core").PluginInstance<"content", Config$3, State$3, Api$3, {
+  "content:ready": {
+    locales: readonly string[];
+    articleCount: number;
+  };
+  "content:invalidated": {
+    paths: readonly string[];
+  };
+}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"head", Config$2, State$2, Api$2, {}> & {
+  meta: typeof meta;
+  og: typeof og;
+  twitter: typeof twitter;
+  jsonLd: typeof jsonLd;
+  canonical: typeof canonical;
+  hreflang: typeof hreflang;
+  feedLink: typeof feedLink;
+  buildArticleHead: typeof buildArticleHead;
+}) | (import("@moku-labs/core").PluginInstance<"build", Config$1, State$1, Api$1, {
+  "build:phase": {
+    phase: PhaseName;
+    status: "start" | "done";
+    durationMs?: number;
+  };
+  "build:complete": {
+    outDir: string;
+    pageCount: number;
+    durationMs: number;
+  };
+}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"spa", SpaConfig, SpaState, SpaApi, {
+  "spa:navigate": {
+    from: string;
+    to: string;
+  };
+  "spa:navigated": {
+    url: string;
+  };
+  "spa:component-mount": {
+    name: string;
+    el: Element;
+  };
+  "spa:component-unmount": {
+    name: string;
+    el: Element;
+  };
+}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"deploy", Config, State, Api, {
+  "deploy:complete": {
+    url: string;
+    deploymentId: string;
+    branch: string;
+    durationMs: number;
+  };
+}> & Record<never, never>) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
+/**
+ * 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] });
+ * ```
+ */
+declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$7, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
 //#endregion
 export { types_d_exports as Build, types_d_exports$1 as Content, types_d_exports$2 as Deploy, types_d_exports$3 as Env, types_d_exports$4 as Head, types_d_exports$5 as Log, types_d_exports$6 as Router, types_d_exports$7 as Spa, buildArticleHead, buildPlugin, canonical, contentPlugin, createApp, createPlugin, defineRoutes, deployPlugin, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };