@levo-so/site-runtime 0.2.2 → 0.3.0

package/index.d.ts

@@ -4,6 +4,27 @@ import { ILevoInsights } from '@levo-so/insights';
 import { JSX } from 'react/jsx-runtime';
 import { LevoQuery } from '@levo-so/core';
 
+/** Color-mode preference. `system` follows the OS `prefers-color-scheme`. */
+export declare type ColorMode = "dark" | "light" | "system";
+
+/**
+ * Site-wide light/dark color mode for a generated Studio site. This does NOT define the
+ * theme (colors/tokens live in `theme.css`) — it only toggles a `light`/`dark` class on
+ * `<html>`; `theme.css` keys its dark token overrides off `.dark` (via `@custom-variant
+ * dark`), so every semantic utility (`bg-page`, `text-ink`, …) flips with zero page changes.
+ *
+ * Mounted once from the scaffold's `__root` (wrapping the page) — deliberately NOT from
+ * `LevoSiteProvider`: that one returns bare children on an unwired site (no `api_url`), and
+ * light/dark can't depend on whether a backend is stamped. `defaultMode` is also a per-site
+ * design decision the generated site owns, not something the runtime should pick.
+ *
+ * SSR-safe: the initial
+ * render uses `defaultMode` and emits only the `ScriptOnce` guard; the stored preference is
+ * read and applied post-mount. Put `suppressHydrationWarning` on `<html>` since the guard
+ * mutates it before hydration.
+ */
+export declare const ColorModeProvider: React.FC<IColorModeProviderProps>;
+
 /**
  * Build the site's `levoHead` from its `site.json`. Each route passes its OWN imported
  * meta file (`head: levoHead(meta)`) — no path matching anywhere; the import IS the
@@ -24,8 +45,11 @@ export declare const createLevoHead: (site: ISiteJson) => (meta?: IPlatformMetaF
  * `levoHead`'s dynamic config reads for per-record heads. An empty `dataSources` ({})
  * resolves to an empty map. Context is typed structurally (just `queryClient`) so the
  * scaffold's router types never enter the package.
+ *
+ * Takes the raw `site.json` — same single input as `createLevoHead` and
+ * `LevoSiteProvider` — and derives the client config itself.
  */
-export declare const createLevoLoader: (config: ILevoSiteConfig) => (sources: ILevoDataSources) => ({ context, params, }: {
+export declare const createLevoLoader: (site: ISiteJson) => (sources: ILevoDataSources) => ({ context, params, }: {
     context: {
         queryClient: IQueryClientLike;
     };
@@ -41,6 +65,27 @@ export declare const createLevoLoader: (config: ILevoSiteConfig) => (sources: IL
  */
 export declare const createSiteClient: (config?: ILevoSiteConfig) => ILevoClient | null;
 
+export declare interface IColorModeProviderProps {
+    children: React.ReactNode;
+    /** Fallback when nothing is stored yet. */
+    defaultMode?: ColorMode;
+    /** localStorage key the preference is persisted under. */
+    storageKey?: string;
+}
+
+export declare interface IColorModeState {
+    /** The stored preference (`system` before it resolves to light/dark). */
+    mode: ColorMode;
+    /**
+     * The mode actually in effect — `system` already resolved against the OS. Use this to
+     * render a two-state toggle so no site has to re-implement the media query. Before mount
+     * it reflects `defaultMode` (with `system` read as light), matching what the server sent.
+     */
+    resolvedMode: ResolvedColorMode;
+    /** Persist a new preference and re-apply it immediately. */
+    setMode: (mode: ColorMode) => void;
+}
+
 export declare interface IComposedHead {
     meta: IHeadEntry[];
     links: IHeadEntry[];
@@ -96,6 +141,16 @@ export declare type IEditorToPreview = {
 } | {
     type: "clear-staged";
     stageId?: string;
+}
+/**
+* Rasterize the CURRENTLY selected element to a PNG data URL (reply:
+* `capture-result`). Selection-state based — no locator round-trip — so it also
+* works for unstamped elements and never suffers stale-locator misses. The editor
+* attaches the result to the chat so the model can see what the user selected.
+*/
+| {
+    type: "capture-selected";
+    requestId: string;
 };
 
 /** A nested element locator — `file:line:col` + occurrence index. Never top-level. */
@@ -136,6 +191,11 @@ export declare interface ILayersNode {
     children: ILayersNode[];
 }
 
+export declare interface ILevoChatProps {
+    /** The site's root `site.json` — all chat props are derived from it. */
+    site: ISiteJson;
+}
+
 /** The shape a page exports so its route loader can prefetch every binding it renders. */
 export declare type ILevoDataSources = Record<string, ILevoSourceDef>;
 
@@ -231,6 +291,14 @@ declare interface ILevoFormTheme {
     gap?: string;
 }
 
+export declare interface ILevoPopupsProps {
+    /**
+     * The site's id (`site.json` `id`) — scopes the active-popups fetch. Absent → the
+     * workspace-wide active popups are returned.
+     */
+    siteId?: string;
+}
+
 /** A single-record binding — one collection record / blog post / event by `slug` (a detail page). */
 export declare interface ILevoRecordConfig {
     module: "collection" | "blog" | "event";
@@ -437,6 +505,37 @@ export declare type IPreviewToEditor = {
 } | {
     type: "highlight-miss";
     element: IElementLocator;
+}
+/**
+* Reply to `capture-selected`. `dataUrl` is a `data:image/png;base64,…` render of the
+* selected element, or null with `error` set ("no-selection", "capture-failed") —
+* always sent, so the editor's pending request settles instead of timing out.
+*/
+| {
+    type: "capture-result";
+    requestId: string;
+    dataUrl: string | null;
+    error?: string;
+}
+/**
+* A select-mode marquee drag finished. `rect` is the dragged area (viewport coords at
+* capture time), `elements` the topmost source-stamped elements substantially inside
+* it (capped — `truncated` set when over the cap), `dataUrl` a PNG render of exactly
+* that area (null when rasterizing failed; the element list is still useful alone).
+* Unlike `capture-selected` this is push-based: one drag = one deliberate intent, so
+* the runtime captures immediately instead of waiting for an editor request.
+*/
+| {
+    type: "region-selected";
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    elements: IRegionElement[];
+    truncated: boolean;
+    dataUrl: string | null;
 };
 
 /**
@@ -452,6 +551,20 @@ export declare interface IQueryClientLike {
     }) => Promise<unknown>;
 }
 
+/**
+ * One element inside a drag-selected region — the lean sibling of
+ * {@link ISelectedElement}: just enough for the AI to locate it (`source`/`index`)
+ * and for the editor to label it. Only source-stamped elements make the list.
+ */
+export declare interface IRegionElement {
+    source: string;
+    index: number;
+    tag: string;
+    label: string;
+    /** Direct display text, truncated. Omitted for non-text containers. */
+    text?: string;
+}
+
 /** The element-selected payload — see `selectedPayload`. */
 export declare interface ISelectedElement {
     tag: string;
@@ -485,17 +598,47 @@ export declare interface ISelectedElement {
     };
 }
 
-/** The slice of the project's root `site.json` the runtime reads. */
+/**
+ * The project's root `site.json` — the ONE input to the whole runtime. The platform stamps
+ * it at provision and re-syncs it on settings saves; the scaffold shim imports it and hands
+ * the same object to every factory (`createLevoHead`, `createLevoLoader`,
+ * `<LevoSiteProvider site>`).
+ *
+ * It lives in its own leaf module because four modules read it (client, scaffold, provider,
+ * chat) and every one of them sits at a different depth of the import graph — hanging the
+ * type off any of them makes the graph cyclic.
+ *
+ * Every field is optional on purpose: a site provisioned before a given block shipped is
+ * missing it entirely, and the runtime must degrade (inert client, hidden widget) rather
+ * than crash.
+ */
 export declare interface ISiteJson {
     id?: string;
     workspace_id?: string;
+    /** Site slug — tags the visitor-chat "Powered by" link's utm_source. */
+    slug?: string;
     name?: string;
     description?: string;
     /** The site's live URL host (with or without protocol) — feeds auto-canonicals. */
     domain?: string;
+    /**
+     * Favicon media object. Its `.location` becomes the site's `<link rel="icon">` and the
+     * visitor-chat header icon. Absent → the site keeps the starter's default `favicon.ico`.
+     */
+    icon?: {
+        location?: string;
+    } | null;
     settings?: {
         head_code?: string;
     };
+    /**
+     * Workspace feature flags stamped into the site. `branding` gates the visitor-chat
+     * "Powered by levo.so" attribution — same flag as the "Made with Levo" page badge.
+     * Absent (not yet stamped) → coerced false → attribution hidden (white-label-safe).
+     */
+    feature_flag?: {
+        branding?: boolean;
+    };
     levo?: {
         api_url?: string;
         insights_url?: string | null;
@@ -507,6 +650,11 @@ export declare interface ISiteJson {
 export declare interface ISiteMeta extends IPageMeta {
     /** "%s · Acme" — %s is the page title. Applied only when the page provides a title. */
     titleTemplate?: string;
+    /**
+     * Favicon URL → `<link rel="icon">`. Site-level only (a per-page favicon isn't a thing),
+     * which is why it lives here rather than on `IPageMeta`.
+     */
+    icon?: string;
 }
 
 export declare type IStagedEntry = IStagedStyleEntry | IStagedTextEntry | IStagedImageEntry;
@@ -544,13 +692,22 @@ export declare interface ITextChangedElement {
     occurrences: number;
 }
 
+/**
+ * Drops the site's AI chat widget onto every page, wired from `site.json`. Mounted once
+ * from the scaffold's `__root` (via the `SiteChat` shim) alongside `<Inspector />`. Self-
+ * gates: renders nothing until the workspace resolves a servable active agent, so an
+ * unwired or agent-less site paints no launcher. `apiBaseUrl` is intentionally left at the
+ * KBChat default (the same-origin `/.levo` proxy) — the serving layer owns that route.
+ */
+export declare const LevoChat: React.FC<ILevoChatProps>;
+
 /**
  * Self-contained event registration widget for generated Studio v3 sites — ticket
  * selection, coupons, attendee details, payment (Razorpay by default; Stripe Embedded
  * Checkout when the booking API returns `provider: "stripe"`), and a booking confirmation.
  *
  * The AI drops this onto an event page and NEVER rebuilds the flow: it owns the entire
- * booking + payment path against the Levo event API. The site client (`useLevoSite`)
+ * booking + payment path against the Levo event API. The site client (`useLevoClient`)
  * auto-stamps the workspace on every request, so no auth/workspace wiring is needed.
  * `external` turns it into a plain link out to a third-party ticketing URL.
  */
@@ -578,13 +735,32 @@ export declare const LevoEventRegister: ({ eventID, title, external, buttonText,
 export declare const LevoForm: React.FC<ILevoFormProps>;
 
 /**
- * Mounts the Levo client + insights for a generated site. Rendered once from the
- * scaffold's `__root` (via the env-reading shim); SSR-safe — construction guards its
- * window/document reads, and `insights.init()` (client-side only by contract) runs in
- * an effect after mount.
+ * Mounts the site's popups, wired from `site.json`. Rendered once from the scaffold's
+ * `__root` (via the `SitePopups` shim), inside `<LevoSiteProvider>` — `PopupLoader` reads
+ * the Levo client through `useLevo()`, which that provider mounts. The library handles
+ * everything else: it fetches active popups, evaluates page/referrer targeting against the
+ * current URL, lazy-loads the renderer only when popups exist, and self-hides otherwise.
+ *
+ * No `pageId` is threaded: that is a studio DB page id with no equivalent in a code-routed
+ * site, so page-bound rules don't apply here — site-wide and URL-path targeting (the
+ * `is_all_pages` / `contains` / `begins_with` matchers) do.
+ */
+export declare const LevoPopups: React.FC<ILevoPopupsProps>;
+
+/**
+ * Mounts the Levo client + insights for a generated site, and the site-wide overlays that
+ * ride on top of it (AI chat + popups). Rendered once from the scaffold's `__root` (via the
+ * env-reading shim); SSR-safe — construction guards its window/document reads, and
+ * `insights.init()` (client-side only by contract) runs in an effect after mount.
+ *
+ * Takes the raw `site.json` and derives everything from it: the data client's config, and
+ * the site-wide overlays' metadata (workspace/name/slug/icon/branding for chat, id for
+ * popups). The overlays render only on a wired site, so they always have a client in scope;
+ * each is client-only, lazy, and self-hiding, so they add nothing to the initial page. Omit
+ * `site` to mount a bare (null) client context.
  */
 export declare const LevoSiteProvider: React.FC<{
-    config?: ILevoSiteConfig;
+    site?: ISiteJson;
     children: React.ReactNode;
 }>;
 
@@ -623,7 +799,7 @@ export declare const parseRawHead: (raw: string) => IComposedHead;
 /**
  * Prefetch every binding a page declares into the router's QueryClient — call it (awaited)
  * from the route `loader` so SSR renders fully-populated HTML. Builds its own client from
- * the site config (loaders run outside React, so `useLevoSite` isn't available). Record
+ * the site config (loaders run outside React, so the client context isn't available). Record
  * bindings pull their slug from the route `params` (`$slug`). Resilient: a single failed
  * source resolves to null so it doesn't blank the whole page — the hook surfaces that
  * binding's error while the rest render.
@@ -642,13 +818,21 @@ export declare const prefetchLevoSources: ({ queryClient, config, sources, param
     params?: Record<string, string>;
 }) => Promise<Record<string, unknown>>;
 
+/** What `system` resolves to — the class actually on `<html>`. */
+export declare type ResolvedColorMode = "dark" | "light";
+
 /**
- * The site's Levo client config from its `site.json`. The platform stamps that file at
- * provision and re-syncs it on settings saves; the `?.` on `levo` is load-bearing — a
- * site provisioned before the block shipped degrades to an inert client, never a crash.
+ * The site's Levo client config from its `site.json` — the only place that mapping lives, so
+ * the provider and the SSR route loader can't drift apart.
+ *
+ * The `?.` on `levo` is load-bearing: a site provisioned before the block shipped degrades to
+ * an inert client, never a crash.
  */
 export declare const siteConfigFromJson: (site: ISiteJson) => ILevoSiteConfig;
 
+/** Read/set the current color mode. Throws outside a `<ColorModeProvider>`. */
+export declare function useColorMode(): IColorModeState;
+
 /**
  * Load a collection's SCHEMA so `LevoForm` can render its fields. Like the other hooks the
  * config is a static literal (the editor binding); it reads the warm cache the route loader
@@ -669,7 +853,11 @@ export declare const useLevoRecord: <T = Record<string, unknown>>(config: ILevoR
 
 /**
  * The site's Levo client, or `null` when the site isn't wired to a Levo backend yet
- * (no `apiUrl` in config — e.g. env not injected at provision). Consumers no-op on null.
+ * (no `api_url` in `site.json` — e.g. not stamped at provision). Consumers no-op on null.
+ *
+ * Site-facing alias only. This package's own components call `@levo-so/react`'s
+ * `useLevoClient()` directly so that nothing internal imports THIS module — which keeps the
+ * provider, and the chat/popup widgets it mounts, off the SSR route-loader's import path.
  *
  * Explicit return type on purpose: inference would inline core-internal names
  * (`IPageContext`) that the rolled-up d.ts doesn't export → TS4023 on declaration emit.