@moku-labs/web 1.12.3 → 1.13.0

package/dist/index.d.cts

@@ -1,343 +1,16 @@
 import { ComponentChildren, FunctionComponent, VNode } from "preact";
+import { Env, Log, Log as Log$1, browserEnv, cloudflareBindings, dotenv, envPlugin, logPlugin, processEnv } from "@moku-labs/common";
 import { EmitFn } from "@moku-labs/core";
 import { BundledTheme, ThemeRegistrationAny } from "shiki";
 import { Pluggable, Processor } from "unified";
 
 //#region \0rolldown/runtime.js
-declare namespace types_d_exports$7 {
-  export { ExpectChain, LogApi, LogConfig, LogEntry, LogLevel, LogSink, LogState };
-}
-/**
- * @file log plugin — type definitions skeleton.
- *
- * Core-plugin type surface: config, state, public API, and the supporting
- * value/sink/assertion-chain types. These types are inferred onto the plugin
- * via state.ts / api.ts; index.ts passes NO explicit generics.
- */
-/**
- * Runtime mode for the log plugin. Selects which default sinks are installed at
- * onInit. The in-memory trace sink is ALWAYS installed regardless of mode.
- *
- * - "test"       — no console sink (keeps test output clean); trace only.
- * - "silent"     — no console sink (explicit quiet); trace only.
- * - "dev"        — console sink + trace.
- * - "production" — console sink + trace.
- */
-type LogConfig = {
-  /** Sink-selection mode. Defaults to `production`. */mode: "test" | "dev" | "production" | "silent";
-};
-/** Severity level for a log entry. */
-type LogLevel = "debug" | "info" | "warn" | "error";
-/**
- * A single recorded log entry.
- */
-type LogEntry = {
-  /** Severity level. */level: LogLevel; /** Event identifier (free-form string; convention: `domain:action`). */
-  event: string; /** Optional structured payload associated with the event. */
-  data?: unknown; /** Capture timestamp in epoch milliseconds (`Date.now()` at append time). */
-  ts: number; /** Optional originating plugin name. Reserved for future enrichment. */
-  plugin?: string;
-};
-/**
- * Pluggable output target. Implement this to add console/file/JSON/etc. sinks
- * WITHOUT changing the log API. Each logged entry is passed to `write` once,
- * in registration order.
- */
-type LogSink = {
-  /**
-   * Write a single entry to this sink.
-   *
-   * @param entry - The entry to emit.
-   */
-  write(entry: LogEntry): void;
-};
-/**
- * Fluent event-trace assertion chain. Reads the live entries array on each call,
- * so assertions reflect the trace state at call time (not chain-creation time).
- * Every method returns the same chain for fluent chaining; assertion failures throw.
- */
-type ExpectChain = {
-  /**
-   * Assert at least one entry has `event`, optionally matching `partial` (subset match).
-   *
-   * @param event - Event name to find.
-   * @param partial - Optional partial data shape (subset-matched against `entry.data`).
-   * @returns The same chain for chaining.
-   * @throws {Error} `LogExpectAssertionError` when no matching entry exists.
-   */
-  toHaveEvent(event: string, partial?: Record<string, unknown>): ExpectChain;
-  /**
-   * Assert all of `events` appear in the trace in the given relative order
-   * (gaps allowed; later events must occur after earlier ones).
-   *
-   * @param events - Ordered list of event names.
-   * @returns The same chain for chaining.
-   * @throws {Error} `LogExpectAssertionError` when the ordering cannot be satisfied.
-   */
-  toHaveEventInOrder(events: string[]): ExpectChain;
-  /**
-   * Assert NO entry has `event` (optionally narrowed by `partial`).
-   *
-   * @param event - Event name that must be absent.
-   * @param partial - Optional partial data shape; only matching entries violate the assertion.
-   * @returns The same chain for chaining.
-   * @throws {Error} `LogExpectAssertionError` when a matching entry exists.
-   */
-  toNotHaveEvent(event: string, partial?: Record<string, unknown>): ExpectChain;
-};
-/**
- * Internal mutable state for the log plugin. Created fresh per createApp construction.
- */
-type LogState = {
-  /** Append-only ordered trace of every logged entry (the in-memory trace sink's backing store). */entries: LogEntry[]; /** Registered output sinks. Each entry is written to every sink in order. */
-  sinks: LogSink[];
-};
-/** Public log API injected as `ctx.log` on every regular plugin and exposed as `app.log`. */
-type LogApi = {
-  /**
-   * Append an `info` entry and fan it out to every sink.
-   *
-   * @param event - Event identifier (convention: `domain:action`).
-   * @param data - Optional structured payload.
-   */
-  info(event: string, data?: unknown): void;
-  /**
-   * Append a `debug` entry and fan it out to every sink.
-   *
-   * @param event - Event identifier (convention: `domain:action`).
-   * @param data - Optional structured payload.
-   */
-  debug(event: string, data?: unknown): void;
-  /**
-   * Append a `warn` entry and fan it out to every sink.
-   *
-   * @param event - Event identifier (convention: `domain:action`).
-   * @param data - Optional structured payload.
-   */
-  warn(event: string, data?: unknown): void;
-  /**
-   * Append an `error` entry. When `error` is provided, its `message`/`stack` are
-   * merged into `data` under an `error` key; otherwise `data` is recorded as-is.
-   *
-   * @param event - Event identifier (convention: `domain:action`).
-   * @param data - Optional structured payload.
-   * @param error - Optional originating Error to merge into `data`.
-   */
-  error(event: string, data?: unknown, error?: Error): void;
-  /**
-   * Return a frozen snapshot of the entries recorded so far (a fresh copy).
-   *
-   * @returns A readonly, frozen copy of the recorded entries.
-   */
-  trace(): readonly LogEntry[];
-  /**
-   * Return a fluent assertion chain bound to the live entries array.
-   *
-   * @returns A fresh {@link ExpectChain}.
-   */
-  expect(): ExpectChain;
-  /**
-   * Register an additional output sink at runtime.
-   *
-   * @param sink - The sink to add to the fan-out list.
-   */
-  addSink(sink: LogSink): void; /** Clear all recorded entries while keeping registered sinks. */
-  reset(): void;
-};
-declare namespace types_d_exports$5 {
-  export { EnvApi, EnvConfig, EnvProvider, EnvState, EnvVarSpec };
-}
-/**
- * @file env plugin — public + boundary type definitions.
- */
-/**
- * A source of raw environment values.
- *
- * Providers are walked in array order during resolution; the first provider to
- * return a non-`undefined` (and non-empty-string) value for a key wins. `load()`
- * is called exactly once per resolution at `onInit` time, after which both env
- * maps are frozen. A provider like {@link cloudflareBindings} reads `globalThis`
- * at that single `onInit` call (not per request).
- *
- * @example
- * ```ts
- * const custom: EnvProvider = {
- *   name: "vault",
- *   load: () => ({ DB_URL: readVaultSecret("db") })
- * };
- * ```
- */
-interface EnvProvider {
-  /** Human-readable provider name, used in diagnostics and error messages. */
-  name: string;
-  /**
-   * Reads this provider's current view of the environment.
-   *
-   * @returns A flat record of variable names to string values. Keys the
-   *   provider cannot supply must be omitted or set to `undefined`.
-   */
-  load(): Record<string, string | undefined>;
-}
-/**
- * Declares how a single environment variable is validated and exposed.
- *
- * @example
- * ```ts
- * const port: EnvVarSpec = { public: false, required: false, default: "3000" };
- * const apiBase: EnvVarSpec = { public: true }; // key must start with PUBLIC_
- * const token: EnvVarSpec = { public: false, required: true, secret: true };
- * ```
- */
-interface EnvVarSpec {
-  /**
-   * Whether the variable is safe to ship to the browser. When `true`, the key
-   * **must** start with {@link EnvConfig.publicPrefix} (cross-checked at
-   * `onInit`), and the variable is included in {@link EnvApi.getPublicMap}.
-   */
-  public: boolean;
-  /** Whether resolution fails if the variable is still undefined after defaults. */
-  required?: boolean;
-  /** Value applied when no provider supplies the variable. */
-  default?: string;
-  /**
-   * Marks the variable as a secret for documentation / tooling. Has no runtime
-   * effect on resolution, but secrets are never permitted to be `public`.
-   */
-  secret?: boolean;
-}
-/**
- * Configuration for the {@link envPlugin} core plugin.
- *
- * @example
- * ```ts
- * createCoreConfig("web", {
- *   plugins: [envPlugin],
- *   pluginConfigs: {
- *     env: {
- *       schema: {
- *         PUBLIC_API_URL: { public: true, default: "/api" },
- *         SESSION_SECRET: { public: false, required: true, secret: true }
- *       }
- *     }
- *   }
- * });
- * ```
- */
-type EnvConfig = {
-  /** Per-variable validation + exposure rules, keyed by variable name. */schema: Record<string, EnvVarSpec>;
-  /**
-   * Ordered list of value sources. The first provider yielding a non-`undefined`
-   * (and non-empty-string) value for a key wins. The plugin's own spec default is
-   * `[]`; the consumer supplies the providers per target (`[dotenv(), processEnv()]`
-   * on Node) — only the `/browser` entry pre-wires `browserEnv()` out of the box.
-   */
-  providers: EnvProvider[];
-  /**
-   * Prefix that public variable names must carry. Bidirectionally enforced at
-   * `onInit`. Framework default is `"PUBLIC_"`.
-   */
-  publicPrefix: string;
-};
-/**
- * Internal env plugin state: the resolved variable table and its public subset.
- * Both maps are populated and frozen (via `freezeMap`) during `onInit`.
- *
- * Exported only to type the `createState` / `api` / `validate` boundary —
- * consumers use {@link EnvApi}, never `EnvState`.
- */
-interface EnvState {
-  /** All validated variables that resolved to a defined value (incl. defaults). */
-  resolved: Map<string, string>;
-  /** Subset of `resolved` where `schema[key].public === true`. */
-  publicMap: Map<string, string>;
-}
-/**
- * The resolved-environment accessor mounted at `ctx.env`. Built by the plugin's
- * `api` factory over `ctx.state` ({@link EnvState}).
- *
- * Available after `onInit` (i.e. inside any plugin's lifecycle and in consumer
- * code). All accessors read from the frozen `resolved` / `publicMap` maps;
- * mutation is impossible.
- *
- * @example
- * ```ts
- * const url = ctx.env.get("PUBLIC_API_URL"); // string | undefined
- * const token = ctx.env.require("DEPLOY_TOKEN"); // string, or throws
- * ```
- */
-type EnvApi = {
-  /**
-   * Reads a resolved variable.
-   *
-   * @param key - Variable name.
-   * @returns The value, or `undefined` if not present / not in schema.
-   */
-  get(key: string): string | undefined;
-  /**
-   * Reads a variable that must exist.
-   *
-   * @param key - Variable name.
-   * @returns The value.
-   * @throws {Error} If the variable is undefined.
-   */
-  require(key: string): string;
-  /**
-   * Tests presence of a resolved variable.
-   *
-   * @param key - Variable name.
-   * @returns `true` if a value is present.
-   */
-  has(key: string): boolean;
-  /**
-   * Returns all public variables as a frozen plain object — convenient for
-   * spreading into a serializable payload.
-   *
-   * @returns A frozen `Record` of public variable names to values.
-   */
-  getPublic(): Readonly<Record<string, string>>;
-  /**
-   * Returns the frozen map of public variables. This is the **sole** intended
-   * input to a build-time `define` injection: every entry is safe to inline
-   * into the browser bundle.
-   *
-   * @returns The frozen public map.
-   */
-  getPublicMap(): ReadonlyMap<string, string>;
-};
-//#endregion
-//#region src/plugins/env/providers.browser.d.ts
-/**
- * A browser-safe {@link EnvProvider} that reads `import.meta.env` and an optional
- * `globalThis[globalKey]` snapshot, merging them with the runtime global winning.
- * Contains zero `node:*` imports, so it is safe to include in the client bundle.
- * Never throws on missing sources — each absent source resolves to `{}`.
- *
- * @param options - Optional settings.
- * @param options.globalKey - `globalThis` key to read a public-env snapshot from. Defaults to `"__ENV__"`.
- * @returns An {@link EnvProvider} named `browser-env`.
- * @example
- * ```ts
- * const provider = browserEnv();
- * provider.load(); // { PUBLIC_API_URL: "/api", ... }
- * ```
- */
-declare function browserEnv(options?: {
-  globalKey?: string;
-}): EnvProvider;
 //#endregion
-//#region src/plugins/env/index.d.ts
+//#region src/config.d.ts
 /**
- * Core plugin that resolves, validates, and freezes the environment at `onInit`,
- * exposing a read-only accessor at `ctx.env`. No `onStart`/`onStop` — holds no resource.
- *
- * @example
- * ```ts
- * createApp({ pluginConfigs: { env: { schema: { PUBLIC_API_URL: { public: true } } } } });
- * ```
+ * @file Framework configuration — Config + Events types, core plugin registration.
+ * @see README.md
  */
-declare const envPlugin: import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>;
-//#endregion
-//#region src/config.d.ts
 /**
  * Deployment stage. Drives content draft visibility — drafts are suppressed
  * only in `"production"`; `"development"` and `"test"` both surface them.
@@ -583,7 +256,7 @@ interface PathMatcher {
     };
   } | null;
 }
-declare namespace types_d_exports$8 {
+declare namespace types_d_exports$6 {
   export { Api$5 as Api, ClientRoute, CompileInput, CompiledRoute, Config$5 as Config, ExtractApi$2 as ExtractApi, ExtractRouteParams, ExtractSegmentParameter, GenerateContext, HeadConfig$1 as HeadConfig, LayoutContext, LoadContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteRequire, RouteState, RouterApi, RouterConfig, RouterState, State$5 as State, TypedRoute, Urls };
 }
 /**
@@ -996,7 +669,7 @@ type Config$5 = RouterConfig;
 type State$5 = RouterState;
 /** Re-export under the canonical `Api` name for the plugin-types barrel. */
 type Api$5 = RouterApi;
-declare namespace types_d_exports$6 {
+declare namespace types_d_exports$5 {
   export { Api$4 as Api, ArticleMeta, Config$4 as Config, HeadConfig, HeadDefaults, HeadElement, ResolvedRoute, State$4 as State };
 }
 /**
@@ -1171,7 +844,7 @@ type Api$4 = {
    */
   composeTitle(head: HeadConfig | undefined): string;
 };
-declare namespace types_d_exports$9 {
+declare namespace types_d_exports$7 {
   export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentHooks, ComponentInstance, ExtractApi$1 as ExtractApi, PageData, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
 }
 /** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
@@ -1237,7 +910,7 @@ interface SpaContext {
   /** Emit a spa lifecycle event (notification-only). */
   emit: SpaEmitFunction;
   /** Structured logger (core `log` API). */
-  readonly log: LogApi;
+  readonly log: Log$1.LogApi;
 }
 /** Configuration for the SPA runtime plugin. All fields optional; defaults applied in onInit. */
 type SpaConfig = {
@@ -3484,16 +3157,6 @@ declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Confi
  */
 declare const i18nPlugin: import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>;
 //#endregion
-//#region src/plugins/log/index.d.ts
-/**
- * Core logging plugin — always-on in-memory trace + `expect()` event-trace DSL.
- * API injected as `ctx.log` on every regular plugin and surfaced as `app.log`.
- * No depends / events / hooks (core plugin per spec/03 §5).
- *
- * @see README.md
- */
-declare const logPlugin: import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>;
-//#endregion
 //#region src/plugins/router/builders/route-builder.d.ts
 /**
  * Create a fluent route builder from a URL pattern string. Captures the pattern
@@ -3662,48 +3325,6 @@ declare const spaPlugin: import("@moku-labs/core").PluginInstance<"spa", SpaConf
   };
 }> & Record<never, never>;
 //#endregion
-//#region src/plugins/env/providers.d.ts
-/**
- * A zero-dependency `.env`-style provider that re-reads and re-parses the file
- * from disk on every `load()`. Missing file resolves to `{}` (optional
- * overrides). Strips a single outer quote pair; does not strip trailing inline
- * comments on unquoted values.
- *
- * @param path - Path to the dotenv file. Defaults to `.env.local`.
- * @returns An {@link EnvProvider} named `dotenv:<path>` that reads fresh per call.
- * @example
- * ```ts
- * const provider = dotenv(".env.local");
- * provider.load(); // { PUBLIC_API_URL: "/api", ... }
- * ```
- */
-declare function dotenv(path?: string): EnvProvider;
-/**
- * A provider that returns a shallow copy of `process.env` at `load()` time.
- *
- * @returns An {@link EnvProvider} named `process-env`.
- * @example
- * ```ts
- * const provider = processEnv();
- * provider.load().HOME; // current process value
- * ```
- */
-declare function processEnv(): EnvProvider;
-/**
- * A provider that reads live, per-request Cloudflare bindings from
- * `globalThis.__CLOUDFLARE_ENV__` at `load()` time (`?? {}` when absent). Never
- * caches the binding object; the consumer owns the global's request lifecycle.
- *
- * @returns An {@link EnvProvider} named `cloudflare`.
- * @example
- * ```ts
- * globalThis.__CLOUDFLARE_ENV__ = env; // set by the request handler
- * const provider = cloudflareBindings();
- * provider.load(); // reads the current request's bindings
- * ```
- */
-declare function cloudflareBindings(): EnvProvider;
-//#endregion
 //#region src/plugins/content/providers.d.ts
 /**
  * The node filesystem content provider: reads + renders Markdown from `contentDir`
@@ -3817,7 +3438,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
     name: string;
     el: Element;
   };
-}> & 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$8, Events, (import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$8, Events, (import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
   route: typeof route;
   defineRoutes: typeof defineRoutes;
   createUrls: typeof createUrls;
@@ -3846,7 +3467,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
     name: string;
     el: Element;
   };
-}> & 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>]>>;
+}> & Record<never, never>) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").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.
@@ -3862,6 +3483,6 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  * const app = createApp({ plugins: [analytics] });
  * ```
  */
-declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
+declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>]>>;
 //#endregion
-export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, types_d_exports$5 as Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, type Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$5 as Head, type Log, types_d_exports$6 as Router, types_d_exports$7 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };