@levo-so/site-runtime 0.1.113 → 0.2.0

package/dist/data/index.d.ts

@@ -86,8 +86,12 @@ export declare const useLevoRecord: <T = Record<string, unknown>>(config: ILevoR
  * 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.
+ * source resolves to null so it doesn't blank the whole page — the hook surfaces that
+ * binding's error while the rest render.
+ *
+ * Returns the fetched values keyed by source key (records as the record object, lists as
+ * `{data, meta}`). The route loader returns this map, making it the route's `loaderData` —
+ * which `levoHead`'s dynamic config reads for per-record titles/descriptions/share images.
  */
 export declare const prefetchLevoSources: ({ queryClient, config, sources, params, }: {
     queryClient: IQueryClientLike;
@@ -97,5 +101,5 @@ export declare const prefetchLevoSources: ({ queryClient, config, sources, param
     sources: ILevoDataSources | undefined;
     /** Route params; record bindings read `params.slug`. */
     params?: Record<string, string>;
-}) => Promise<void>;
+}) => Promise<Record<string, unknown>>;
 //# sourceMappingURL=index.d.ts.map

package/dist/data/index.js

@@ -61,19 +61,21 @@ var i = (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();
+	if (!l || !r) return {};
+	let u = await Promise.all(Object.entries(r).map(async ([e, n]) => {
+		if (n.mode === "record") {
+			let r = c?.slug;
+			return r ? [e, await t.ensureQueryData({
+				queryKey: a(n, r),
+				queryFn: () => s(l, n, r)
+			}).catch(() => null)] : [e, null];
 		}
-		return t.ensureQueryData({
-			queryKey: i(e),
-			queryFn: () => o(l, e)
-		}).catch(() => void 0);
+		return [e, await t.ensureQueryData({
+			queryKey: i(n),
+			queryFn: () => o(l, n)
+		}).catch(() => null)];
 	}));
+	return Object.fromEntries(u);
 };
 //#endregion
 export { u as prefetchLevoSources, l as useLevoRecord, c as useLevoSource };

package/dist/index.d.ts

@@ -23,4 +23,6 @@ export type { ILevoSiteConfig } from './LevoSiteProvider';
 export { LevoSiteProvider, useLevoInsights, useLevoSite } from './LevoSiteProvider';
 export type { IComposedHead, IPageMeta, ISiteMeta } from './pageHead';
 export { PageHead, pageHead, parseRawHead } from './pageHead';
+export type { ILevoDynamicHead, IPlatformMetaFile, IPlatformPageMeta, ISiteJson, } from './scaffold';
+export { createLevoHead, createLevoLoader, siteConfigFromJson } from './scaffold';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,4 +3,5 @@ import { LevoSiteProvider as t, useLevoInsights as n, useLevoSite as r } from ".
 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 };
+import { createLevoHead as d, createLevoLoader as f, siteConfigFromJson as p } from "./scaffold.js";
+export { s as Inspector, t as LevoSiteProvider, c as PageHead, d as createLevoHead, f as createLevoLoader, e as createSiteClient, l as pageHead, u as parseRawHead, i as prefetchLevoSources, p as siteConfigFromJson, n as useLevoInsights, a as useLevoRecord, r as useLevoSite, o as useLevoSource };

package/dist/inspector/stagedOverrides.d.ts

@@ -1,5 +1,5 @@
-import { IStagedEntry } from './protocol';
 import { IOriginalsStash } from './originalsStash';
+import { IStagedEntry } from './protocol';
 export type IStagedOverrides = ReturnType<typeof createStagedOverrides>;
 export declare const createStagedOverrides: (deps: {
     originals: IOriginalsStash;

package/dist/pageHead.d.ts

@@ -10,6 +10,8 @@ export interface IPageMeta {
         title?: string;
         description?: string;
         image?: string;
+        /** Absolute share URL. Falls back to `canonical` when unset. */
+        url?: string;
         /** Defaults to "website" when any og field is present. */
         type?: string;
     };

package/dist/pageHead.js

@@ -44,8 +44,8 @@ var r = (e) => JSON.stringify(e).replace(/<\//g, "<\\/"), i = (e) => {
 	let f = {
 		...t.og,
 		...e.og
-	}, p = f.title ?? i ?? o, m = f.description ?? l;
-	(p || m || f.image) && (n.meta.push({
+	}, p = f.title ?? i ?? o, m = f.description ?? l, h = !!(p || m || f.image), g = f.url ?? d;
+	h && (n.meta.push({
 		property: "og:type",
 		content: f.type ?? "website"
 	}), p && n.meta.push({
@@ -57,26 +57,29 @@ var r = (e) => JSON.stringify(e).replace(/<\//g, "<\\/"), i = (e) => {
 	}), f.image && n.meta.push({
 		property: "og:image",
 		content: f.image
+	}), g && n.meta.push({
+		property: "og:url",
+		content: g
 	}));
-	let h = {
+	let _ = {
 		...t.twitter,
 		...e.twitter
-	}, g = h.title ?? p, _ = h.description ?? m, v = h.image ?? f.image;
-	(g || _ || v) && (n.meta.push({
+	}, v = _.title ?? p, y = _.description ?? m, b = _.image ?? f.image;
+	(v || y || b) && (n.meta.push({
 		name: "twitter:card",
-		content: h.card ?? "summary_large_image"
-	}), g && n.meta.push({
+		content: _.card ?? "summary_large_image"
+	}), v && n.meta.push({
 		name: "twitter:title",
-		content: g
-	}), _ && n.meta.push({
+		content: v
+	}), y && n.meta.push({
 		name: "twitter:description",
-		content: _
-	}), v && n.meta.push({
+		content: y
+	}), b && n.meta.push({
 		name: "twitter:image",
-		content: v
+		content: b
 	}));
-	let y = e.ldJson ? Array.isArray(e.ldJson) ? e.ldJson : [e.ldJson] : [];
-	for (let e of y) n.scripts.push({
+	let x = e.ldJson ? Array.isArray(e.ldJson) ? e.ldJson : [e.ldJson] : [];
+	for (let e of x) n.scripts.push({
 		type: "application/ld+json",
 		children: r(e)
 	});

package/dist/scaffold.d.ts

@@ -0,0 +1,110 @@
+import { ILevoSiteConfig } from './client';
+import { ILevoDataSources, IQueryClientLike } from './data';
+import { IComposedHead } from './pageHead';
+/** The platform's per-page SEO object — the `meta` key of `meta/<route>.json`. */
+export interface IPlatformPageMeta {
+    meta_title?: string;
+    meta_description?: string;
+    keywords?: string;
+    og_title?: string;
+    og_description?: string;
+    /** Plain URL string, or the platform media object (older rows) — `.location` is read. */
+    og_image?: string | {
+        location?: string;
+    } | null;
+    og_url?: string;
+    canonical?: string;
+    twitter_card?: string;
+    /** JSON-LD structured data — rendered as an `application/ld+json` script tag. */
+    ld_json?: Record<string, unknown> | Array<Record<string, unknown>>;
+    /** Page-scoped raw head snippet — script/meta/link tags only. */
+    head_code?: string;
+    disable_indexing?: boolean;
+    robots?: string;
+}
+/** The full `meta/<route>.json` shape: page identity (platform-owned) + the SEO object. */
+export interface IPlatformMetaFile {
+    title?: string;
+    description?: string;
+    meta?: IPlatformPageMeta;
+}
+/** The slice of the project's root `site.json` the runtime reads. */
+export interface ISiteJson {
+    id?: string;
+    workspace_id?: string;
+    name?: string;
+    description?: string;
+    /** The site's live URL host (with or without protocol) — feeds auto-canonicals. */
+    domain?: string;
+    settings?: {
+        head_code?: string;
+    };
+    levo?: {
+        api_url?: string;
+        insights_url?: string | null;
+        app_mode?: string;
+    };
+}
+/**
+ * Per-record head config for a dynamic (`$slug`) route — `levoHead`'s optional second
+ * argument. A static literal (AI/editor-written, next to the route's meta import); each
+ * field names a FIELD on the loaded record (the `dataSources` entry named by `source`).
+ * At request time the record's values override the static meta file per-field, so every
+ * slug ships its own title, description, and share image.
+ */
+export interface ILevoDynamicHead {
+    /** Key in the page's `dataSources` whose loaded record feeds the head. */
+    source: string;
+    /** Record field holding the page title (the site name is appended automatically). */
+    title?: string;
+    /** Record field holding the description. */
+    description?: string;
+    /** Record field holding the share image (platform image object or URL). */
+    image?: string;
+}
+/**
+ * The slice of the router's head-fn context we read. Structural on purpose (like
+ * IQueryClientLike) so the package never depends on the router's types: `loaderData` is
+ * the loader's return value — `prefetchLevoSources`' source-keyed map — and
+ * `match.pathname` is the request path. Both read defensively; absent = skipped.
+ */
+interface IHeadCtx {
+    loaderData?: unknown;
+    match?: {
+        pathname?: string;
+    };
+}
+/**
+ * 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.
+ */
+export declare const siteConfigFromJson: (site: ISiteJson) => ILevoSiteConfig;
+/**
+ * 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
+ * pairing. The argument default lets a meta-less route render pure site defaults.
+ *
+ * Dynamic (`$slug`) routes pass a second argument naming the record fields that feed the
+ * head (`head: levoHead(meta, { source: "post", title: "title", … })`), so every slug
+ * gets its own title/description/share image instead of the route's shared static meta.
+ * Pages that set no `canonical` get a self-referencing one derived from the site domain
+ * + request path (og:url follows it in pageHead) — per-slug correct on dynamic routes.
+ */
+export declare const createLevoHead: (site: ISiteJson) => (meta?: IPlatformMetaFile, dynamic?: ILevoDynamicHead) => (ctx?: IHeadCtx) => IComposedHead;
+/**
+ * Build the one-line route loader (`loader: levoLoader(dataSources)`): prefetch the
+ * page's declared data sources on the server so SSR ships fully-rendered HTML, and
+ * return them keyed by source key — that map is the route's `loaderData`, which
+ * `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.
+ */
+export declare const createLevoLoader: (config: ILevoSiteConfig) => (sources: ILevoDataSources) => ({ context, params, }: {
+    context: {
+        queryClient: IQueryClientLike;
+    };
+    params?: Record<string, string>;
+}) => Promise<Record<string, unknown>>;
+export {};
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.js

@@ -0,0 +1,64 @@
+import { prefetchLevoSources as e } from "./data/index.js";
+import { pageHead as t } from "./pageHead.js";
+//#region src/scaffold.ts
+var n = (e) => typeof e == "string" && e.trim() ? e : void 0, r = (e) => ({
+	apiUrl: e.levo?.api_url || "",
+	workspace: e.workspace_id || "",
+	siteId: e.id || "",
+	insightsUrl: e.levo?.insights_url || null,
+	appMode: e.levo?.app_mode || "production"
+}), i = (e) => typeof e == "string" ? e : e?.location ?? void 0, a = (e, t) => {
+	let n = e.meta ?? {}, r = e.title && t ? `${e.title} | ${t}` : e.title || t || void 0;
+	return {
+		title: n.meta_title || r,
+		description: n.meta_description || void 0,
+		canonical: n.canonical || void 0,
+		robots: n.disable_indexing ? "noindex,nofollow" : n.robots || void 0,
+		og: {
+			title: n.og_title || void 0,
+			description: n.og_description || void 0,
+			image: i(n.og_image),
+			url: n.og_url || void 0
+		},
+		twitter: { card: n.twitter_card || void 0 },
+		ldJson: n.ld_json || void 0,
+		customHead: n.head_code || void 0
+	};
+}, o = (e) => ({
+	description: e.description || void 0,
+	customHead: e.settings?.head_code || void 0
+}), s = (e) => (r = {}, s) => (c) => {
+	let l = a(r, e.name);
+	if (s) {
+		let t = c?.loaderData?.[s.source];
+		if (t) {
+			let r = s.title ? n(t[s.title]) : void 0;
+			r && (l.title = e.name ? `${r} | ${e.name}` : r, l.og = {
+				...l.og,
+				title: r
+			});
+			let a = s.description ? n(t[s.description]) : void 0;
+			a && (l.description = a, l.og = {
+				...l.og,
+				description: a
+			});
+			let o = s.image ? i(t[s.image]) : void 0;
+			o && (l.og = {
+				...l.og,
+				image: o
+			});
+		}
+	}
+	if (!l.canonical) {
+		let t = c?.match?.pathname, n = (e.domain || "").trim();
+		n && t?.startsWith("/") && (l.canonical = (/^https?:\/\//.test(n) ? n : `https://${n}`).replace(/\/+$/, "") + t);
+	}
+	return t(l, o(e));
+}, c = (t) => (n) => ({ context: r, params: i }) => e({
+	queryClient: r.queryClient,
+	config: t,
+	sources: n,
+	params: i
+});
+//#endregion
+export { s as createLevoHead, c as createLevoLoader, r as siteConfigFromJson };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levo-so/site-runtime",
-  "version": "0.1.113",
+  "version": "0.2.0",
   "description": "Runtime for Levo Studio v3 sites — the editor preview inspector, page head metadata, and the Levo data client.",
   "type": "module",
   "publishConfig": {