@levo-so/site-runtime 0.1.113

package/README.md

@@ -0,0 +1,93 @@
+# @levo-so/site-runtime
+
+Everything that runs **inside** a Levo Studio v3 site (the TanStack Start apps forked from
+`levo-api/studio/starter`):
+
+| Export | What it is |
+|---|---|
+| `Inspector` | The editor-preview element inspector — select / text-edit / staged DOM overrides / layers snapshot, driven by the dashboard over postMessage. Imported directly by the scaffold's `__root`. Inert outside the editor preview. |
+| `PageHead` / `pageHead` / `parseRawHead` | Per-page document metadata composed from SEO-editor sidecars (`src/pages/<page>.meta.ts`) + site defaults (`_site.meta.ts`). |
+| `LevoSiteProvider` / `useLevoSite` / `useLevoInsights` | The Levo client + insights (`createLevoClient` from `@levo-so/core`, `createLevoInsights` from `@levo-so/insights` — core-only, no UI-kit tree). Mounted once from `__root` via the scaffold's `src/lib/levo/provider.tsx` shim, which feeds `VITE_LEVO_API_URL` / `VITE_LEVO_WORKSPACE` / `VITE_LEVO_SITE_ID` / `VITE_LEVO_INSIGHTS_URL` / `VITE_LEVO_APP_MODE`. Both hooks return `null` on an unwired site — consumers stay inert; a null `insightsUrl` runs trackers/identity with zero network. |
+| `IEditorToPreview` / `IPreviewToEditor` + friends | The editor ↔ preview wire contract (types only). The dashboard's `previewMessaging.ts` re-exports these (`IOutboundMessage`/`IInboundMessage` aliases), so a contract change here is a compile error on both sides. |
+
+## How sites consume it
+
+**Direct imports** — `__root` imports `Inspector` from the package, and the studio SEO
+editor splices `import { PageHead } from "@levo-so/site-runtime"` into pages it wires.
+No compat shims: old deployments get nuked, not patched (a conscious trade — there is no
+File-API shadow-hotfix; a runtime fix ships via publish → image rebuild → re-provision).
+
+The **only** `src/lib/` file left in the scaffold is the env-injection shim — it exists
+because Vite injects `import.meta.env` into site-source modules only, never into packaged
+deps:
+
+```tsx
+// src/lib/levo/provider.tsx — reads VITE_LEVO_API_URL / VITE_LEVO_WORKSPACE /
+// VITE_LEVO_SITE_ID / VITE_LEVO_INSIGHTS_URL / VITE_LEVO_APP_MODE →
+// <LevoSiteProvider config={…}>, mounted once by __root.
+```
+
+## Update propagation (read before "why isn't my fix live?")
+
+Sites do **not** install dependencies. `node_modules` is baked into the `levo-studio-base`
+image and copied into a per-site named Docker volume at provision — then frozen (hibernate/
+wake is `docker stop`/`start`). So:
+
+- **New sites** pick up a release once `starter/package.json` bumps and the base image rebuilds.
+- **Existing sites** keep the version their volume was provisioned with until their
+  container + volume are recreated from a newer image (a WM "roll" operation — doesn't exist
+  yet) — or, per current policy, are simply nuked and re-provisioned.
+- Consequence: the fleet updates out from under generated code. The public API here must
+  stay strictly backward-compatible.
+
+## Local development
+
+- **In-monorepo (daily loop):** `pnpm --filter @levo-so/site-runtime dev` (watch build);
+  consumers in this workspace link via `workspace:*`.
+- **Against the real starter:** `scripts/create-dev-site.sh` generates a machine-local
+  copy of `levo-api/studio/starter` (default `<repos-parent>/studio-dev-site`, port 3200)
+  with this package `file:`-linked (npm symlinks it, so watch builds propagate),
+  `resolve.dedupe: ["react", "react-dom"]` in its Vite config (two Reacts = hooks crash),
+  and the demo fixture pages copied in. The copy deliberately lives
+  OUTSIDE the monorepo — real sites npm-install standalone, so it must not inherit the
+  workspace's pnpm version overrides or node_modules layout; re-run the script (`--force`)
+  whenever the starter changes. Run its `npm run dev` + the package watch build, then flip
+  the commented `NEXT_PUBLIC_STUDIO_LOCAL_PREVIEW_TEMPLATE` toggle in the dashboard's
+  `env/.env.localhost`. Full editor ↔ runtime loop, no Docker. (File-API writes still
+  target the provisioned project, not the host-run site — Apply visibly "reverts" there.)
+- **Full pipeline:** rebuild `levo-studio-base:dev` against a `pnpm pack` tarball or a
+  changesets snapshot release (`changeset version --snapshot && changeset publish --tag dev`).
+
+## Source layout
+
+The whole inspector runtime lives in `src/inspector/`: `index.tsx` is the composition
+root (modes, selection + observer arbitration, pointer tracking — the timing-interlocked
+core) wiring the subsystem factories: `editorChannel` (send + origin lock),
+`originalsStash` (pre-edit text), `textEditController` (contenteditable lifecycle),
+`stagedOverrides` (override registry + sheet), `messageRouter` (inbound dispatch),
+`historyWatcher` (SPA nav). `dom.ts` holds the pure DOM helpers; `protocol.ts` the wire
+contract. `src/pageHead.tsx` and `src/LevoSiteProvider.tsx` are independent of the inspector.
+
+## Shipping a runtime change (starter adopted 2026-07-10)
+
+The golden starter (`levo-api/studio/starter`) consumes this package from the registry
+(`^0.3.0`) with direct imports (`__root` → `Inspector`; the SEO splicer writes the
+package import). The pipeline for a change:
+
+1. Changeset → `changeset version` → **publish** (`pnpm --filter @levo-so/site-runtime
+   publish`, needs npm creds — the publish MUST land before the next `levo-studio-base`
+   image build, which is the only thing that ever installs it).
+2. A patch (`0.2.x`) flows into the next image build automatically; a minor (`0.3.0`)
+   also needs the starter's range bumped.
+3. New sites pick it up once the image rebuilds; existing sites keep their frozen volume
+   until re-provisioned (nuke policy) or a WM roll op exists.
+
+## Protocol change checklist
+
+1. Change `src/inspector/protocol.ts` (and the runtime behavior in `src/inspector/`),
+   then rebuild — the dashboard type-checks against `dist/`.
+2. `pnpm --filter levo-dashboard check-types` — the dashboard imports this contract, so
+   drift shows up as compile errors there (its `IInspectorElement` stays a deliberately
+   looser WORKING type for palette/Layers-constructed partials; that one is not the wire).
+3. Add a changeset; note the change in `docs/studio-v3/site-runtime/README.md` (the
+   protocol changelog).

package/dist/LevoSiteProvider.d.ts

@@ -0,0 +1,25 @@
+import { ILevoClient } from '@levo-so/core';
+import { ILevoInsights } from '@levo-so/insights';
+import { ILevoSiteConfig } from './client';
+export type { ILevoSiteConfig };
+/**
+ * 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.
+ *
+ * Explicit return type on purpose: inference would inline core-internal names
+ * (`IPageContext`) that its rolled-up d.ts doesn't export → TS4023 on declaration emit.
+ */
+export declare const useLevoSite: () => ILevoClient | null;
+/** The site's insights (analytics/track), or `null` on an unwired site. */
+export declare const useLevoInsights: () => ILevoInsights | null;
+/**
+ * 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.
+ */
+export declare const LevoSiteProvider: React.FC<{
+    config?: ILevoSiteConfig;
+    children: React.ReactNode;
+}>;
+//# sourceMappingURL=LevoSiteProvider.d.ts.map

package/dist/LevoSiteProvider.js

@@ -0,0 +1,23 @@
+import { createSiteClient as e } from "./client.js";
+import { createLevoInsights as t } from "@levo-so/insights";
+import { createContext as n, useContext as r, useState as i } from "react";
+import { jsx as a } from "react/jsx-runtime";
+//#region src/LevoSiteProvider.tsx
+var o = n(null), s = () => r(o)?.client ?? null, c = () => r(o)?.insights ?? null, l = ({ config: n, children: r }) => {
+	let [s] = i(() => {
+		let r = e(n);
+		return r ? {
+			client: r,
+			insights: t(r, {
+				insightsUrl: n?.insightsUrl || null,
+				site: n?.siteId || null
+			})
+		} : null;
+	});
+	return /* @__PURE__ */ a(o.Provider, {
+		value: s,
+		children: r
+	});
+};
+//#endregion
+export { l as LevoSiteProvider, c as useLevoInsights, s as useLevoSite };

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+import { ILevoClient } from '@levo-so/core';
+/** Site-level Levo config — the scaffold shim fills this from Vite env. */
+export interface ILevoSiteConfig {
+    /** Origin of the Levo public API / proxy the site's data calls go through. */
+    apiUrl?: string;
+    /** The site's workspace id (`W…`). Invalid/absent → client runs workspace-less. */
+    workspace?: string;
+    /** The site's id, stamped onto analytics events. */
+    siteId?: string;
+    /**
+     * Analytics reverse-proxy URL. Absent/null → identity + DOM trackers still run
+     * (popup triggers work) but nothing is sent — queued events are dropped.
+     */
+    insightsUrl?: string | null;
+    /** Forwarded to the client's APP_MODE; defaults to "production". */
+    appMode?: string;
+}
+/**
+ * Build the site's core Levo client from config, or `null` when the site isn't wired to a
+ * backend yet (no `apiUrl`). SSR-safe — `createLevoClient` guards its window/document reads.
+ *
+ * Explicit return type on purpose: inference would inline core-internal names its rolled-up
+ * d.ts doesn't export → TS4023 on declaration emit.
+ */
+export declare const createSiteClient: (config?: ILevoSiteConfig) => ILevoClient | null;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,14 @@
+import { createLevoClient as e } from "@levo-so/core";
+//#region src/client.ts
+var t = (t) => {
+	let n = (t?.apiUrl || "").replace(/\/$/, "");
+	return n ? e({
+		apiUrl: n,
+		workspace: t?.workspace ? t.workspace : null,
+		appName: "studio-site",
+		NODE_ENV: "",
+		APP_MODE: t?.appMode || "production"
+	}) : null;
+};
+//#endregion
+export { t as createSiteClient };

package/dist/data/index.d.ts

@@ -0,0 +1,101 @@
+import { LevoQuery } from '@levo-so/core';
+import { ILevoSiteConfig } from '../client';
+/**
+ * The minimal QueryClient surface `prefetchLevoSources` needs. Structural on purpose — a
+ * branded `QueryClient` type in the public API would clash whenever the consuming site
+ * resolves a different `@tanstack/react-query` copy/version than the one this package was
+ * built against (peer dep). Any real QueryClient satisfies this.
+ */
+export interface IQueryClientLike {
+    ensureQueryData: (options: {
+        queryKey: readonly unknown[];
+        queryFn: () => Promise<unknown>;
+    }) => Promise<unknown>;
+}
+/** A list binding — collection records or blog posts matching `query`. */
+export interface ILevoSourceConfig {
+    /** Only "collection" | "blog" today — the core client has no event/community module. */
+    module: "collection" | "blog";
+    /** Collection key / blog key. */
+    identifier: string;
+    /** where / sort / limit / page / search. `limit: -1` = all. */
+    query?: LevoQuery.FindQuery;
+    /** Reserved (blog sub-module identifiers etc.); round-tripped through the binding. */
+    options?: Record<string, unknown>;
+}
+export interface ILevoSourceResult<T = Record<string, unknown>> {
+    /** null until loaded, on error, and on an unwired site. */
+    data: T[] | null;
+    meta: {
+        total: number;
+        pages: number;
+    } | null;
+    isLoading: boolean;
+    error: string | null;
+    /** Spread onto the container that renders the list — stamps the editor binding. */
+    bind: {
+        "data-levo-source": string;
+    };
+}
+/** A single-record binding — one collection record / blog post by `slug` (a detail page). */
+export interface ILevoRecordConfig {
+    module: "collection" | "blog";
+    identifier: string;
+    /**
+     * Reserved for field projection. The slug endpoints return the whole record today, so
+     * this is round-tripped through the binding but not yet sent to the API.
+     */
+    query?: Pick<LevoQuery.FindQuery, "select" | "include">;
+}
+export interface ILevoRecordResult<T = Record<string, unknown>> {
+    data: T | null;
+    isLoading: boolean;
+    error: string | null;
+    bind: {
+        "data-levo-source": string;
+    };
+}
+/**
+ * One entry in a page's `dataSources` export — a list or record binding, discriminated by
+ * `mode`. The route loader reads these to prefetch; the page passes each to its hook. `mode`
+ * is optional for lists (the default) and required for records (so the loader knows to use
+ * the route slug).
+ */
+export type ILevoSourceDef = (ILevoSourceConfig & {
+    mode?: "list";
+}) | (ILevoRecordConfig & {
+    mode: "record";
+});
+/** The shape a page exports so its route loader can prefetch every binding it renders. */
+export type ILevoDataSources = Record<string, ILevoSourceDef>;
+/**
+ * Render a LIST of platform content. The config is a static literal (the editor rewrites
+ * it). Reads the router QueryClient: if the route loader prefetched this binding, the first
+ * render has data (SSR ships it); otherwise it fetches client-side. Always render a loading
+ * and an empty state — `data` is null before the first load and on unwired sites.
+ */
+export declare const useLevoSource: <T = Record<string, unknown>>(config: ILevoSourceConfig) => ILevoSourceResult<T>;
+/**
+ * Render ONE record by slug — a detail page. `slug` is a RUNTIME arg (the page's route
+ * param), kept OUT of the config literal so the binding stays static and editable. No slug
+ * (or unwired site) → inert. `data` null after load = not found: render a friendly fallback.
+ */
+export declare const useLevoRecord: <T = Record<string, unknown>>(config: ILevoRecordConfig, slug: string | undefined) => ILevoRecordResult<T>;
+/**
+ * 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
+ * bindings pull their slug from the route `params` (`$slug`). Resilient: a single failed
+ * source resolves to a cached error so it doesn't blank the whole page — the hook surfaces
+ * that binding's error while the rest render.
+ */
+export declare const prefetchLevoSources: ({ queryClient, config, sources, params, }: {
+    queryClient: IQueryClientLike;
+    /** Site env config — same object the LevoSiteProvider receives. */
+    config: ILevoSiteConfig | undefined;
+    /** The page's `dataSources` export (undefined = page has none). */
+    sources: ILevoDataSources | undefined;
+    /** Route params; record bindings read `params.slug`. */
+    params?: Record<string, string>;
+}) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/data/index.js

@@ -0,0 +1,79 @@
+import { createSiteClient as e } from "../client.js";
+import { useLevoSite as t } from "../LevoSiteProvider.js";
+import { getLevoError as n } from "@levo-so/core";
+import { useQuery as r } from "@tanstack/react-query";
+//#region src/data/index.ts
+var i = (e) => [
+	"levo-source",
+	"list",
+	e.module,
+	e.identifier,
+	e.query ?? null,
+	e.options ?? null
+], a = (e, t) => [
+	"levo-source",
+	"record",
+	e.module,
+	e.identifier,
+	t ?? null
+], o = async (e, t) => {
+	let n = t.module === "collection" ? await e.collection.getCollectionContentList({
+		collection_key: t.identifier,
+		...t.query ?? {}
+	}) : await e.blog.getAllBlogs(t.identifier, t.query ?? {});
+	return {
+		data: n.content.data ?? [],
+		meta: n.content.meta ?? null
+	};
+}, s = async (e, t, n) => (t.module === "collection" ? await e.collection.getCollectionContent({
+	collection_key: t.identifier,
+	slug: n
+}) : await e.blog.getSingleBlog(t.identifier, n)).content.data ?? null, c = (e) => {
+	let a = t(), s = r({
+		queryKey: i(e),
+		queryFn: () => o(a, e),
+		enabled: !!a
+	});
+	return {
+		data: s.data?.data ?? null,
+		meta: s.data?.meta ?? null,
+		isLoading: s.isLoading,
+		error: s.error ? n(s.error).message : null,
+		bind: { "data-levo-source": JSON.stringify({
+			mode: "list",
+			...e
+		}) }
+	};
+}, l = (e, i) => {
+	let o = t(), c = r({
+		queryKey: a(e, i),
+		queryFn: () => s(o, e, i),
+		enabled: !!o && !!i
+	});
+	return {
+		data: c.data ?? null,
+		isLoading: c.isLoading,
+		error: c.error ? n(c.error).message : null,
+		bind: { "data-levo-source": JSON.stringify({
+			mode: "record",
+			...e
+		}) }
+	};
+}, u = async ({ queryClient: t, config: n, sources: r, params: c }) => {
+	let l = e(n);
+	!l || !r || await Promise.all(Object.values(r).map((e) => {
+		if (e.mode === "record") {
+			let n = c?.slug;
+			return n ? t.ensureQueryData({
+				queryKey: a(e, n),
+				queryFn: () => s(l, e, n)
+			}).catch(() => void 0) : Promise.resolve();
+		}
+		return t.ensureQueryData({
+			queryKey: i(e),
+			queryFn: () => o(l, e)
+		}).catch(() => void 0);
+	}));
+};
+//#endregion
+export { u as prefetchLevoSources, l as useLevoRecord, c as useLevoSource };

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @levo-so/site-runtime — everything that runs INSIDE a Levo Studio v3 site:
+ *
+ * - `Inspector` — the editor-preview element inspector (select / text-edit / staged
+ *   overrides / layers snapshot), driven by the dashboard over postMessage. Mounted by
+ *   the scaffold's `__root`; inert outside the editor preview (it only reacts to the
+ *   editor's messages).
+ * - `PageHead` / `pageHead` — per-page document metadata composed from SEO-editor
+ *   sidecars + site defaults.
+ * - `LevoSiteProvider` / `useLevoSite` — the Levo client (core-only), mounted from
+ *   `__root` via the scaffold's env-reading shim.
+ * - the editor ↔ preview message contract types (`IEditorToPreview` / `IPreviewToEditor`).
+ *
+ * Sites import the package directly; the scaffold's single `src/lib/levo/provider.tsx`
+ * shim exists only to read Vite env (not injected into packaged deps) into the provider.
+ */
+export { createSiteClient } from './client';
+export type { ILevoDataSources, ILevoRecordConfig, ILevoRecordResult, ILevoSourceConfig, ILevoSourceDef, ILevoSourceResult, IQueryClientLike, } from './data';
+export { prefetchLevoSources, useLevoRecord, useLevoSource } from './data';
+export { Inspector } from './inspector';
+export type { IEditorToPreview, IElementLocator, IHistoryFn, ILayersNode, IPageSource, IPatchedHistoryFn, IPreviewToEditor, ISelectedElement, IStagedEntry, IStagedStyleEntry, IStagedTextEntry, ITextChangedElement, } from './inspector/protocol';
+export type { ILevoSiteConfig } from './LevoSiteProvider';
+export { LevoSiteProvider, useLevoInsights, useLevoSite } from './LevoSiteProvider';
+export type { IComposedHead, IPageMeta, ISiteMeta } from './pageHead';
+export { PageHead, pageHead, parseRawHead } from './pageHead';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,6 @@
+import { createSiteClient as e } from "./client.js";
+import { LevoSiteProvider as t, useLevoInsights as n, useLevoSite as r } from "./LevoSiteProvider.js";
+import { prefetchLevoSources as i, useLevoRecord as a, useLevoSource as o } from "./data/index.js";
+import { Inspector as s } from "./inspector/index.js";
+import { PageHead as c, pageHead as l, parseRawHead as u } from "./pageHead.js";
+export { s as Inspector, t as LevoSiteProvider, c as PageHead, e as createSiteClient, l as pageHead, u as parseRawHead, i as prefetchLevoSources, n as useLevoInsights, a as useLevoRecord, r as useLevoSite, o as useLevoSource };

package/dist/inspector/dom.d.ts

@@ -0,0 +1,56 @@
+import { ILayersNode, IPageSource, ISelectedElement, IStagedStyleEntry } from './protocol';
+export declare const Z: {
+    readonly ring: 99997;
+    readonly overlay: 99998;
+    readonly label: 99999;
+};
+export declare const COLOR: {
+    readonly hover: "#3b82f6";
+    readonly hoverBg: "rgba(59,130,246,0.12)";
+    readonly hoverLabelBg: "#1d4ed8";
+    readonly select: "#16a34a";
+    readonly selectGlow: "rgba(22,163,74,0.18)";
+};
+export declare const sourceOf: (el: Element | null) => string | null;
+export declare const nodesForSource: (src: string) => Element[];
+export declare const sourceIndex: (el: Element, src: string) => number;
+export declare const nodeForSource: (src: string, idx?: number) => Element | null;
+export declare const addStagedKey: (el: Element, stageId: string) => void;
+export declare const removeStagedKey: (el: Element, stageId: string) => void;
+export declare const cssRuleFor: (stageId: string, entry: IStagedStyleEntry) => string;
+/** Create the four overlay artifacts (hover box + label, selection ring + label). */
+export declare const createOverlayNodes: () => {
+    overlay: HTMLDivElement;
+    label: HTMLDivElement;
+    ring: HTMLDivElement;
+    ringLabel: HTMLDivElement;
+};
+/** Glue a box + its label to an element's viewport rect (shared by the hover overlay and
+ * the selection ring — the label clamp + above/below flip live in one place). */
+export declare const positionBox: (box: HTMLElement, boxLabel: HTMLElement, el: Element) => void;
+export declare const externalLinkHref: (target: EventTarget | null) => string | null;
+export declare const isTextLeaf: (el: Element) => boolean;
+/**
+ * Everything a selection report carries about `el` — shared by click-picks and the inbound
+ * `select-element` command so both emit the identical element-selected shape. `fullText` is
+ * present ONLY for a source-stamped text-leaf (so the editor never offers a text edit that
+ * would destroy nested markup). The 120-slice `text` feeds labels, not the editor.
+ */
+export declare const selectedPayload: (el: Element) => ISelectedElement;
+/**
+ * Every `data-levo-source` binding container on the page — the reply to `request-sources`,
+ * feeding the editor's page-level Data manager (a list of bindings without needing a
+ * selection). Unlike `sourceBindingOf` (nearest ancestor of a clicked node), this enumerates
+ * the containers themselves. Binding containers are few (one per bound region), so the
+ * per-container `sourceIndex` re-query is cheap — no layers-tree-style single-pass needed.
+ */
+export declare const enumerateSources: () => IPageSource[];
+/**
+ * Snapshot the live DOM for the editor's Layers panel. Pure pull — no observers, no pushes.
+ * `ownNodes` are the runtime's overlay artifacts to skip.
+ */
+export declare const buildLayersTree: (ownNodes: readonly Element[]) => {
+    tree: ILayersNode;
+    truncated: boolean;
+};
+//# sourceMappingURL=dom.d.ts.map