API reference

function createApp<const ExtraPlugins extends readonly AnyPluginInstance[] = readonly []>(options?: {
  plugins?: ExtraPlugins;
  config?: { stage?: "production" | "development" | "test"; mode?: "ssg" | "spa" | "hybrid" };
  pluginConfigs?: { [pluginName: string]: Partial<PluginConfig> };
  onReady?: (ctx: AppCallbackContext) => void;
  onError?: (error: Error, ctx: AppCallbackContext) => void;
  onStart?: (ctx: AppCallbackContext) => void | Promise<void>;
  onStop?: (ctx: AppCallbackContext) => void | Promise<void>;
}): App;

function createPlugin<Name extends string, Config, State, Api, Deps, Events, Hooks, Helpers>(
  name: Name,
  spec: {
    config?: Config;
    depends?: Deps;
    createState?: (ctx: { global; config }) => State;
    events?: (register) => Events;
    api?: (ctx: PluginContext) => Api;
    hooks?: (ctx: PluginContext) => Hooks;
    helpers?: Helpers;
    onInit?: (ctx: PluginContext) => void;
    onStart?: (ctx: PluginContext) => void | Promise<void>;
    onStop?: (ctx: { global; config; state }) => void | Promise<void>;
  }
): PluginInstance<Name, Config, State, Api, Events> & Helpers;

import { createPlugin, spaPlugin } from "@moku-labs/web/browser";

export const visitsPlugin = createPlugin("visits", {
  depends: [spaPlugin],
  config: { limit: 50 },
  createState: (): { urls: string[] } => ({ urls: [] }),
  events: register => ({
    "visits:full": register<{ count: number }>("The visit list reached its limit")
  }),
  hooks: ctx => ({
    "spa:navigated": ({ url }) => {
      ctx.state.urls.push(url);
      if (ctx.state.urls.length === ctx.config.limit) ctx.emit("visits:full", { count: ctx.state.urls.length });
    }
  }),
  api: ctx => ({ recent: () => [...ctx.state.urls] })
});

function route<P extends string>(pattern: P): RouteBuilder<RouteState<P>>;
function defineRoutes<T extends RouteMap>(routes: T): T;
function createUrls<T extends RouteMap>(routes: T, defaultLocale?: string): Urls<T>;

interface RouteBuilder<S extends RouteState> extends RouteDefinition {
  load<D>(loader: (ctx: LoadContext<S>) => D | Promise<D>): RouteBuilder<{ params: S["params"]; data: Awaited<D> }>;
  generate(handler: (ctx: GenerateContext) => S["params"][] | Promise<S["params"][]>): RouteBuilder<S>;
  render(handler: (ctx: RouteContext<S>) => VNode): RouteBuilder<S>;
  head(handler: (ctx: RouteContext<S>) => HeadConfig): RouteBuilder<S>;
  layout(component: (ctx: LayoutContext<S>, children: ComponentChildren) => VNode): RouteBuilder<S>;
  meta(meta: Record<string, unknown>): RouteBuilder<S>;
  transition(mode: "none" | "crossfade" | "slide" | "morph"): RouteBuilder<S>;
  scroll(mode: "top" | "preserve"): RouteBuilder<S>;
  toJson(handler: (ctx: RouteContext<S>) => unknown): RouteBuilder<S>;
  toFile(handler: (params: S["params"]) => string): RouteBuilder<S>;
}

interface Urls<T extends RouteMap> {
  toUrl<K extends keyof T & string>(name: K, params?: Record<string, string>): string;
}

function createIsland<S extends object = object, A = unknown>(name: string, spec: IslandSpec<S, A>): IslandDef;

interface IslandSpec<S, A> {
  state?: (ctx: IslandContext<S>) => S;
  render?: (state: Readonly<S>, ctx: IslandContext<S>) => VNode | Node | string | null | void;
  events?: Record<string, (ctx: IslandContext<S>, event: Event, target: Element) => void>;
  api?: (ctx: IslandContext<S>) => A;
  onCreate?(ctx: IslandContext<S>): void;
  onMount?(ctx: IslandContext<S>): void;
  onNavStart?(ctx: IslandContext<S>): void;
  onNavEnd?(ctx: IslandContext<S>): void;
  onUnMount?(ctx: IslandContext<S>): void;
  onDestroy?(ctx: IslandContext<S>): void;
}

const lazyEmbed: IslandDef;
function navigate(path: string, options?: { scroll?: "top" | "preserve"; replace?: boolean }): void;
function hardNavigate(url: string): void;
function createChannel<T>(options: ChannelOptions<T>): Channel<T>;

interface ChannelOptions<T> {
  url: (id: string) => string;
  parse?: (raw: string) => T | undefined; // default: JSON.parse, dropping frames that fail
  keepAlive?: { send: string; ignore?: string; everyMs?: number }; // everyMs default 30000
  reconnect?: { baseMs?: number; maxMs?: number } | false; // default 500 → 8000, doubling
  bufferUntilSeed?: boolean; // default false
  shouldReconnect?: (event: CloseEvent) => boolean;
}

interface Channel<T> {
  subscribe(id: string, handler: (message: T) => void): () => void;
  seed(id: string): void;
  deliverLocal(id: string, message: T): void;
  send(raw: string): void;
  current(): string | undefined;
  disconnect(): void;
}

function meta(name: string, content: string): HeadElement;
function og(property: string, content: string): HeadElement;
function twitter(name: string, content: string): HeadElement;
function jsonLd(data: unknown): HeadElement;
function canonical(url: string): HeadElement;
function hreflang(locale: string, url: string): HeadElement;
function feedLink(title: string, url: string, type?: string): HeadElement;
function buildArticleHead(articleMeta: ArticleMeta, canonicalUrl: string): HeadElement[];

type HeadElement = { tag: "meta" | "link" | "title" | "script"; attrs?: Record<string, string>; children?: string; key?: string };
type ArticleMeta = { title: string; description?: string; author?: string; published?: string; modified?: string; section?: string; tags?: string[]; image?: string };

function collectionUrl(baseUrl: string, collection: string, shard: string): string;
function loadCollectionShard<T>(baseUrl: string, collection: string, shard: string): Promise<T>;

function fileSystemContent(options: FileSystemContentOptions): ContentProvider;
function EmbedFacadeButton(props: EmbedFacadeProps): VNode;
function GalleryTrack(props: GalleryProps): VNode;

import type { Content, Router } from "@moku-labs/web/browser";

type CardContext = Router.RouteContext<Router.RouteState<"/{lang:?}/", Content.ArticleCard[]>>;

export function ArticleList(ctx: CardContext) {
  return (
    <ul>
      {ctx.data.map(card => (
        <li key={card.contentId}>
          <a href={card.url}>{card.title}</a>
        </li>
      ))}
    </ul>
  );
}

function mountIsland<S extends object = object, A = unknown>(definition: IslandDef, options?: MountIslandOptions): IslandHandle<S, A>;
function renderIsland<S extends object>(render: IslandRender<S>, input: { state: S; ctx?: Partial<IslandContext<S>> }): RenderIslandResult;