@blocksdiy/blocks-client-sdk 1.24.2 → 1.25.1

package/dist/app/app-shape/bundle-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-shape.d.ts","sourceRoot":"","sources":["../../../src/app/app-shape/bundle-shape.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAGlE,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,0FAA0F;IAC1F,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,qCAAqC;IACrC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,kGAAkG;IAClG,OAAO,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAwCD,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,uFAAuF;IACvF,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAKD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,cAAc,GAAG,SAAS,EAAE,OAAO,MAAM,GAAG,SAAS,KAAG,QAoB/F,CAAC;AAmBF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,QA+BnE,CAAC"}

package/dist/app/app-shape/bundle-shape.js

@@ -0,0 +1,118 @@
+import { buildBlocksRoutes, srcRelativePath } from "./route-tree";
+/**
+ * Flatten the routes-mode tree into legacy-shaped page entries so missing-page reporting and the
+ * "no pages" check work unchanged. Leaf nodes are pages (nodes with children are layouts); the
+ * route id doubles as the name.
+ */
+const flattenRoutePages = (nodes) => {
+    const pages = [];
+    const visit = (node) => {
+        if (!node.children && (node.index || node.path)) {
+            pages.push({ id: node.id, name: node.id, component: node.Component });
+        }
+        node.children?.forEach(visit);
+    };
+    nodes.forEach(visit);
+    return pages;
+};
+/** A pages-mode app's routes for error reports: each page at its name and its id, as the tree routes it. */
+const pageRoutes = (pages) => pages.flatMap(({ id, name }) => [{ id, path: name }, ...(name === id ? [] : [{ id, path: id }])]);
+const routesShape = (routes, chatComponentRenderer) => ({
+    routes,
+    pages: flattenRoutePages(routes.routes),
+    chatComponentRenderer,
+    // The tree IS a RouteObject tree; the extra `id`/`name` metadata is ignored.
+    errorRoutes: routes.routes,
+    isEmpty: false,
+});
+const pagesShape = (pages, layout, chatComponentRenderer) => ({
+    pages,
+    layout,
+    chatComponentRenderer,
+    errorRoutes: pageRoutes(pages),
+    isEmpty: pages.length === 0,
+});
+/** The bundle's exports that are not pages. */
+const BUNDLE_META_EXPORTS = new Set(["__blocksRoutes", "__agentChatCodeComponent", "AppLayout"]);
+/**
+ * The shape of a compiled bundle the host imported, in any of its three forms: a routes-mode
+ * module (`__blocksRoutes`), a legacy module (`AppLayout` plus one named export per page), or the
+ * oldest, a `window["compiler_<appId>"]` map of one-character-prefixed page ids. An EMPTY routes tree (every route module failed to derive, e.g. no default exports)
+ * takes the legacy branch, so the "Could not load the components" fatal still fires.
+ */
+export const shapeFromBundle = (bundle, appId) => {
+    const chatComponentRenderer = bundle?.__agentChatCodeComponent;
+    if (bundle?.__blocksRoutes?.routes?.length) {
+        return routesShape(bundle.__blocksRoutes, chatComponentRenderer);
+    }
+    if (bundle) {
+        const pages = Object.entries(bundle)
+            .filter(([name]) => !BUNDLE_META_EXPORTS.has(name))
+            .map(([, page]) => page);
+        return pagesShape(pages, bundle.AppLayout, chatComponentRenderer);
+    }
+    const windowPages = window[`compiler_${appId}`];
+    const pages = Object.entries(windowPages ?? {}).map(([blockId, component]) => ({
+        id: blockId.substring(1),
+        name: blockId.substring(1),
+        component,
+    }));
+    return pagesShape(pages, undefined, chatComponentRenderer);
+};
+/** The chat-component renderer's module, at the path the app's `src/main.tsx` globs it. */
+const CHAT_COMPONENT_RENDERER_FILE = "components/ui/agent-chat-code-component.tsx";
+/** A pages-mode app's `layout.tsx`, as the compiler exports it. */
+const LAYOUT_ID = "AppLayout";
+/** The landing page of a pages-mode app, by file name, as the compiler picks it; else its first page. */
+const LANDING_PAGE_NAMES = ["main", "home", "index", "dashboard"];
+const landingPageId = (pages) => {
+    for (const preferred of LANDING_PAGE_NAMES) {
+        const page = pages.find(({ name }) => name.slice(name.lastIndexOf("/") + 1).toLowerCase() === preferred);
+        if (page) {
+            return page.id;
+        }
+    }
+    return pages[0]?.id;
+};
+/**
+ * The shape of a self-mounting app from the modules its `src/main.tsx` globbed, by the rule the
+ * compiler builds a bundle with: an app with a module under `routes/` is routes mode (`routes/**`
+ * and `root.tsx` make the tree), else `pages/**` are its pages, each at its file name inside
+ * `layout.tsx`. `components/ui/agent-chat-code-component.tsx`, when the app has the agent-chat
+ * item, is its chat-component renderer.
+ */
+export const shapeFromModules = (modules) => {
+    let chatComponentRenderer;
+    let layout;
+    let hasRouteModules = false;
+    const routeModules = {};
+    const pages = [];
+    for (const modulePath of Object.keys(modules).sort()) {
+        const module = modules[modulePath];
+        const file = srcRelativePath(modulePath);
+        if (file === CHAT_COMPONENT_RENDERER_FILE) {
+            chatComponentRenderer = module;
+        }
+        else if (file === "layout.tsx") {
+            layout = { id: LAYOUT_ID, name: LAYOUT_ID, component: module?.default };
+        }
+        else if (file.startsWith("pages/") && file.endsWith(".tsx")) {
+            // As the compiler exports it, default export or not: a page without one crashes in its own
+            // boundary, which names it to the builder.
+            const name = file.slice("pages/".length, -".tsx".length);
+            pages.push({ id: name, name, component: module?.default });
+        }
+        else {
+            hasRouteModules ||= file.startsWith("routes/");
+            routeModules[modulePath] = module;
+        }
+    }
+    if (hasRouteModules) {
+        const routes = buildBlocksRoutes(routeModules);
+        // An empty tree (every route module failed to derive) is an app with no page, as for a bundle.
+        return routes.routes.length
+            ? routesShape(routes, chatComponentRenderer)
+            : pagesShape([], undefined, chatComponentRenderer);
+    }
+    return { ...pagesShape(pages, layout, chatComponentRenderer), defaultPageId: landingPageId(pages) };
+};

package/dist/app/app-shape/route-tree.d.ts

@@ -0,0 +1,33 @@
+/**
+ * File-system routing: the folder structure under `src/routes/` IS the URL structure (conventions:
+ * the boilerplate's pages-and-routing skill). The app's `src/main.tsx` imports every route module
+ * with an eager `import.meta.glob` and hands the flat module map here, which folds it into the
+ * nested tree `BlocksApp` gives React Router's `useRoutes`:
+ *
+ *  - a file                  → a route node (`[x]` → `:x`, `index` → index route,
+ *                              `not-found` → the folder's catch-all 404)
+ *  - folder WITH layout.tsx  → parent node; children render into its <Outlet/>
+ *  - folder WITHOUT layout   → no node; children get compound paths ("admin/Users")
+ *
+ * The compiler mirrors this derivation when route files sync to blocks
+ * (apps/compiler/src/modules/git-sync/fs-routes-path.ts) — keep identical.
+ */
+import { type ComponentType } from "react";
+import type { BlocksRouteNode, BlocksRoutesTree } from "../types.js";
+/** A module map as `import.meta.glob(..., { eager: true })` produces it. */
+export type RouteModules = Record<string, {
+    default?: ComponentType;
+} | undefined>;
+/**
+ * The module's path from `src/`, whichever form the glob gave it: absolute from the project root
+ * (`/src/routes/x.tsx`) or relative to `src/main.tsx` (`./routes/x.tsx`).
+ */
+export declare const srcRelativePath: (modulePath: string) => string;
+/** Fold the route module map (the `src/routes/**` entries) into route nodes. */
+export declare function deriveRouteNodes(modules: RouteModules): BlocksRouteNode[];
+/**
+ * The app's route tree from the modules its `src/main.tsx` globbed: every `routes/**` module and
+ * `root.tsx` (the root layout; absent, a bare outlet).
+ */
+export declare function buildBlocksRoutes(modules: RouteModules): BlocksRoutesTree;
+//# sourceMappingURL=route-tree.d.ts.map

package/dist/app/app-shape/route-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-tree.d.ts","sourceRoot":"","sources":["../../../src/app/app-shape/route-tree.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAG3C,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAElE,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,aAAa,CAAA;CAAE,GAAG,SAAS,CAAC,CAAC;AAenF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,YAAY,MAAM,KAAG,MAAiE,CAAC;AAyFvH,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,eAAe,EAAE,CAiBzE;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CAezE"}

package/dist/app/app-shape/route-tree.jsx

@@ -0,0 +1,137 @@
+import { Outlet } from "react-router";
+/** `[city]` → `:city`, `[...rest]` → `*`, anything else stays literal. */
+function mapSegment(segment) {
+    const splat = segment.match(/^\[\.\.\..*\]$/);
+    if (splat) {
+        return "*";
+    }
+    const param = segment.match(/^\[(.+)\]$/);
+    if (param) {
+        return `:${param[1]}`;
+    }
+    return segment;
+}
+/**
+ * The module's path from `src/`, whichever form the glob gave it: absolute from the project root
+ * (`/src/routes/x.tsx`) or relative to `src/main.tsx` (`./routes/x.tsx`).
+ */
+export const srcRelativePath = (modulePath) => modulePath.replace(/^\/src\//, "").replace(/^\.\//, "");
+const newFolder = () => ({ files: new Map(), folders: new Map() });
+function buildFolderTree(modules) {
+    const root = newFolder();
+    for (const modulePath of Object.keys(modules).sort()) {
+        const Component = modules[modulePath]?.default;
+        if (!Component) {
+            console.error(`[blocks] Route module has no default export: ${modulePath}`);
+            continue;
+        }
+        // "routes/concerts/[city].tsx" → ["concerts", "[city].tsx"]
+        const file = srcRelativePath(modulePath);
+        const segments = file.replace(/^routes\//, "").split("/");
+        if (segments.some((segment) => segment.startsWith("."))) {
+            continue;
+        }
+        let folder = root;
+        for (const dir of segments.slice(0, -1)) {
+            if (!folder.folders.has(dir)) {
+                folder.folders.set(dir, newFolder());
+            }
+            folder = folder.folders.get(dir);
+        }
+        const base = segments[segments.length - 1].replace(/\.tsx$/, "");
+        folder.files.set(base, { file, Component });
+    }
+    return root;
+}
+/**
+ * Convert a folder into route nodes. `pathPrefix` accumulates the segments of
+ * layout-less ancestor folders.
+ */
+function folderToNodes(folder, pathPrefix) {
+    const nodes = [];
+    const joinPath = (...parts) => parts.filter(Boolean).join("/");
+    for (const [base, entry] of folder.files) {
+        if (base === "layout") {
+            continue; // consumed by the parent folder conversion
+        }
+        const id = entry.file.replace(/\.tsx$/, "");
+        if (base === "index") {
+            nodes.push({
+                id,
+                // An index route matches the parent path. With a layout-less prefix it
+                // still needs the accumulated segments as its own path.
+                ...(pathPrefix ? { path: pathPrefix } : { index: true }),
+                Component: entry.Component,
+            });
+        }
+        else {
+            nodes.push({
+                id,
+                // `not-found.tsx` is the folder's 404 (Next.js-style): a catch-all
+                // matching any URL nothing else in the folder matches. Splats rank
+                // lowest in React Router, so it never shadows real routes.
+                path: joinPath(pathPrefix, base === "not-found" ? "*" : mapSegment(base)),
+                Component: entry.Component,
+            });
+        }
+    }
+    for (const [dirName, sub] of folder.folders) {
+        const segment = mapSegment(dirName);
+        const layout = sub.files.get("layout");
+        if (layout) {
+            nodes.push({
+                id: layout.file.replace(/\.tsx$/, ""),
+                path: joinPath(pathPrefix, segment),
+                Component: layout.Component,
+                children: folderToNodes(sub, ""),
+            });
+        }
+        else {
+            // No layout — the folder contributes URL segments only; children are
+            // hoisted to this level with compound paths.
+            nodes.push(...folderToNodes(sub, joinPath(pathPrefix, segment)));
+        }
+    }
+    return nodes;
+}
+/** Fold the route module map (the `src/routes/**` entries) into route nodes. */
+export function deriveRouteNodes(modules) {
+    const root = buildFolderTree(modules);
+    const nodes = folderToNodes(root, "");
+    // A top-level routes/layout.tsx wraps ALL routes (inside src/root.tsx) —
+    // same folder rule as everywhere else, with src/routes/ being the folder.
+    // It becomes a pathless layout route so every URL renders through it.
+    const rootLayout = root.files.get("layout");
+    if (rootLayout) {
+        return [
+            {
+                id: rootLayout.file.replace(/\.tsx$/, ""),
+                Component: rootLayout.Component,
+                children: nodes,
+            },
+        ];
+    }
+    return nodes;
+}
+const FallbackRoot = () => <Outlet />;
+/**
+ * The app's route tree from the modules its `src/main.tsx` globbed: every `routes/**` module and
+ * `root.tsx` (the root layout; absent, a bare outlet).
+ */
+export function buildBlocksRoutes(modules) {
+    const routeModules = {};
+    let rootModule;
+    for (const [modulePath, module] of Object.entries(modules)) {
+        const file = srcRelativePath(modulePath);
+        if (file === "root.tsx") {
+            rootModule = module;
+        }
+        else if (file.startsWith("routes/") && file.endsWith(".tsx")) {
+            routeModules[modulePath] = module;
+        }
+    }
+    return {
+        root: { id: "root", Component: rootModule?.default ?? FallbackRoot },
+        routes: deriveRouteNodes(routeModules),
+    };
+}

package/dist/app/app-shape/use-app-shape.d.ts

@@ -0,0 +1,13 @@
+import type { AppShape } from "./bundle-shape.js";
+/** The app's code as `BlocksApp` shaped it, with when it arrived. */
+export type LoadedAppShape = AppShape & {
+    /** Stamps the code's arrival: the tree remounts on it after a recompile, so new code takes over cleanly. */
+    componentsLoadedAt: number | undefined;
+};
+export declare const AppShapeContext: import("react").Context<LoadedAppShape | undefined>;
+/**
+ * The app's code as shaped (its routes or pages, layout and chat renderer) with its load stamp, for
+ * the tree and for the host's layers in it.
+ */
+export declare const useAppShape: () => LoadedAppShape;
+//# sourceMappingURL=use-app-shape.d.ts.map

package/dist/app/app-shape/use-app-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-app-shape.d.ts","sourceRoot":"","sources":["../../../src/app/app-shape/use-app-shape.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG;IACtC,4GAA4G;IAC5G,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC,CAAC;AAEF,eAAO,MAAM,eAAe,qDAAuD,CAAC;AAEpF;;;GAGG;AACH,eAAO,MAAM,WAAW,QAAO,cAM9B,CAAC"}

package/dist/app/app-shape/use-app-shape.js

@@ -0,0 +1,13 @@
+import { createContext, useContext } from "react";
+export const AppShapeContext = createContext(undefined);
+/**
+ * The app's code as shaped (its routes or pages, layout and chat renderer) with its load stamp, for
+ * the tree and for the host's layers in it.
+ */
+export const useAppShape = () => {
+    const shape = useContext(AppShapeContext);
+    if (!shape) {
+        throw new Error("useAppShape must be used within BlocksApp");
+    }
+    return shape;
+};

package/dist/app/dev-server/bootstrap.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The dev server has no host page: `pnpm dev` serves the boilerplate's own `index.html`, so the
+ * app hosts itself. Once, before the first render, this stands in for app-render's boot — the app
+ * is the one the workspace is for, the token is whatever the developer (or the builder's sandbox)
+ * stored, and the theme comes from the app's own stylesheet.
+ */
+export declare const ensureSelfHost: () => void;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/app/dev-server/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../../src/app/dev-server/bootstrap.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAiCjC,CAAC"}

package/dist/app/dev-server/bootstrap.js

@@ -0,0 +1,43 @@
+import { getGoogleBaseUrl, getHost } from "@blocksdiy/blocks-client-api/envService";
+import { devConfig, tokenStorageKey } from "../../dev-config.js";
+import { getBlocksHostState, setBlocksHost, THEME_MODE_STORAGE_KEY } from "../host.js";
+import { loadFontsFromTheme } from "./fonts.js";
+/**
+ * The dev server has no host page: `pnpm dev` serves the boilerplate's own `index.html`, so the
+ * app hosts itself. Once, before the first render, this stands in for app-render's boot — the app
+ * is the one the workspace is for, the token is whatever the developer (or the builder's sandbox)
+ * stored, and the theme comes from the app's own stylesheet.
+ */
+export const ensureSelfHost = () => {
+    if (getBlocksHostState()) {
+        return;
+    }
+    // Only the dev server declares itself: anywhere else, an empty store means the tree has no host
+    // (or the page loaded a second copy of the SDK), which the tree fails on rather than host the app
+    // on its own.
+    const dev = devConfig();
+    if (!dev) {
+        return;
+    }
+    const appId = dev.appId;
+    if (!appId) {
+        throw new Error("BlocksApp has no host: set window.__BLOCKS_DEV__.appId (VITE_APP_ID) for the dev server");
+    }
+    // The SDK's URL helpers read it (`getLoginUrl`, `getPageUrl`).
+    window.appId = appId;
+    const token = window.localStorage.getItem(tokenStorageKey()) ?? undefined;
+    const themeMode = window.localStorage.getItem(THEME_MODE_STORAGE_KEY) || "system";
+    // The platform the workspace points at takes the login's requests and its Google sign-in alike.
+    const apiHost = dev?.apiHost?.replace(/\/$/, "");
+    setBlocksHost({
+        config: {
+            baseUrl: apiHost || getHost().replace(/\/$/, ""),
+            googleBaseUrl: apiHost || getGoogleBaseUrl(),
+        },
+        app: { id: appId, name: document.title || "App", compiledAt: 0 },
+        token,
+        requiresSignIn: !token,
+        themeMode,
+    });
+    loadFontsFromTheme();
+};

package/dist/app/dev-server/fonts.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Load Google Fonts from the theme's CSS variables (--font-sans, --font-serif, --font-mono) on the
+ * dev server, where no host injects the theme: mirrors app-render's font loading so the app looks
+ * the same as it does live.
+ */
+/** Read the font variables off the document and load any non-system Google Font through a <link>. */
+export declare function loadFontsFromTheme(): void;
+//# sourceMappingURL=fonts.d.ts.map

package/dist/app/dev-server/fonts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../../../src/app/dev-server/fonts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiDH,qGAAqG;AACrG,wBAAgB,kBAAkB,IAAI,IAAI,CAoBzC"}

package/dist/app/dev-server/fonts.js

@@ -0,0 +1,67 @@
+/**
+ * Load Google Fonts from the theme's CSS variables (--font-sans, --font-serif, --font-mono) on the
+ * dev server, where no host injects the theme: mirrors app-render's font loading so the app looks
+ * the same as it does live.
+ */
+const buildFontCssUrl = (family, weights = ["400"]) => {
+    const encodedFamily = encodeURIComponent(family);
+    const weightsParam = weights.join(";");
+    return `https://fonts.googleapis.com/css2?family=${encodedFamily}:wght@${weightsParam}&display=swap`;
+};
+const loadGoogleFont = (family, weights = ["400", "700"]) => {
+    const href = buildFontCssUrl(family, weights);
+    if (document.querySelector(`link[href="${href}"]`)) {
+        return;
+    }
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = href;
+    document.head.appendChild(link);
+};
+const SYSTEM_FONTS = [
+    "ui-sans-serif",
+    "ui-serif",
+    "ui-monospace",
+    "system-ui",
+    "sans-serif",
+    "serif",
+    "monospace",
+    "cursive",
+    "fantasy",
+];
+function extractFontFamily(fontFamilyValue) {
+    if (!fontFamilyValue) {
+        return null;
+    }
+    const firstFont = fontFamilyValue.split(",")[0]?.trim();
+    if (!firstFont) {
+        return null;
+    }
+    const cleanFont = firstFont.replace(/['"]/g, "");
+    if (SYSTEM_FONTS.includes(cleanFont.toLowerCase())) {
+        return null;
+    }
+    return cleanFont;
+}
+const FONT_VARS = ["--font-sans", "--font-serif", "--font-mono", "--font-inter", "--font-inter-tight"];
+/** Read the font variables off the document and load any non-system Google Font through a <link>. */
+export function loadFontsFromTheme() {
+    if (typeof document === "undefined") {
+        return;
+    }
+    const computed = getComputedStyle(document.documentElement);
+    const weights = ["400", "500", "600", "700"];
+    const seen = new Set();
+    for (const varName of FONT_VARS) {
+        const family = extractFontFamily(computed.getPropertyValue(varName).trim());
+        if (family && !seen.has(family)) {
+            seen.add(family);
+            try {
+                loadGoogleFont(family, weights);
+            }
+            catch (e) {
+                console.warn("Failed to load Google font:", family, e);
+            }
+        }
+    }
+}

package/dist/app/hooks/use-scroll-to-top-on-page-change.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Client-side navigation keeps the document's scroll offset: pushState never resets it, and the
+ * declarative <BrowserRouter> has no <ScrollRestoration>, so a new page landed on from the bottom
+ * of the previous one would open already scrolled to its end. This applies the rule
+ * ScrollRestoration applies to new locations, narrowed on purpose:
+ *
+ * - Only a PATH change counts. Search/hash-only changes are left alone — tabs, filters and
+ *   pagination update `?params` in place and must not jump the page.
+ * - Back/forward (POP) is left to the browser, which restores its own saved offset.
+ * - The boot location is never touched; a reload keeps whatever the browser restores.
+ * - A visible fragment target on the new path wins over the top of the page.
+ *
+ * Layout effect so the reset lands before paint (no one-frame flash of the old offset), and
+ * `behavior: "instant"` so an app-level `scroll-behavior: smooth` can't animate it.
+ */
+export declare const useScrollToTopOnPageChange: () => void;
+//# sourceMappingURL=use-scroll-to-top-on-page-change.d.ts.map

package/dist/app/hooks/use-scroll-to-top-on-page-change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-scroll-to-top-on-page-change.d.ts","sourceRoot":"","sources":["../../../src/app/hooks/use-scroll-to-top-on-page-change.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,YAuBtC,CAAC"}

package/dist/app/hooks/use-scroll-to-top-on-page-change.js

@@ -0,0 +1,55 @@
+import { useLayoutEffect, useRef } from "react";
+import { NavigationType, useLocation, useNavigationType } from "react-router";
+/**
+ * The element a `#fragment` points at, if it can be scrolled to. Null for no fragment, no such
+ * element, or one without a layout box (hidden): `scrollIntoView` would silently do nothing
+ * there, and the page must still end up somewhere deterministic. Malformed percent-encoding in
+ * a hand-typed URL must not throw out of a layout effect that sits above the app's error boundary.
+ */
+const getHashTarget = (hash) => {
+    if (!hash) {
+        return null;
+    }
+    try {
+        const target = document.getElementById(decodeURIComponent(hash.slice(1)));
+        return target?.getClientRects().length ? target : null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Client-side navigation keeps the document's scroll offset: pushState never resets it, and the
+ * declarative <BrowserRouter> has no <ScrollRestoration>, so a new page landed on from the bottom
+ * of the previous one would open already scrolled to its end. This applies the rule
+ * ScrollRestoration applies to new locations, narrowed on purpose:
+ *
+ * - Only a PATH change counts. Search/hash-only changes are left alone — tabs, filters and
+ *   pagination update `?params` in place and must not jump the page.
+ * - Back/forward (POP) is left to the browser, which restores its own saved offset.
+ * - The boot location is never touched; a reload keeps whatever the browser restores.
+ * - A visible fragment target on the new path wins over the top of the page.
+ *
+ * Layout effect so the reset lands before paint (no one-frame flash of the old offset), and
+ * `behavior: "instant"` so an app-level `scroll-behavior: smooth` can't animate it.
+ */
+export const useScrollToTopOnPageChange = () => {
+    const { pathname, hash } = useLocation();
+    const navigationType = useNavigationType();
+    const previousPathnameRef = useRef(pathname);
+    useLayoutEffect(() => {
+        if (pathname === previousPathnameRef.current) {
+            return;
+        }
+        previousPathnameRef.current = pathname;
+        if (navigationType === NavigationType.Pop) {
+            return;
+        }
+        const hashTarget = getHashTarget(hash);
+        if (hashTarget) {
+            hashTarget.scrollIntoView({ behavior: "instant", block: "start" });
+            return;
+        }
+        window.scrollTo({ top: 0, left: 0, behavior: "instant" });
+    }, [pathname, hash, navigationType]);
+};

package/dist/app/host.d.ts

@@ -0,0 +1,106 @@
+import { type ComponentType, type ReactNode } from "react";
+import type { RouteObject } from "react-router";
+import type { User } from "../ClientSdk.js";
+import type { AppType, ThemeMode } from "./types.js";
+/**
+ * The host contract: what the page hosting a Blocks app tells the app's tree, how it extends the
+ * tree, and what the tree reports back. Blocks' own hosting (app-render: a browser tab, the
+ * builder's canvas, the mobile app) implements it; so can a page of your own. `BlocksApp` reads one
+ * module-level store, so the state reaches the tree whichever root renders it, and survives a bundle
+ * swap: the host sets it before importing a bundle and never tears it down. The dev server has no
+ * host page; there the tree hosts itself (`dev-server/bootstrap.ts`).
+ */
+/** What the host knows, kept current as it changes; a flag left out is off. */
+export interface BlocksHostState {
+    /** The platform's origins, for the login and the app lookups. */
+    config: {
+        baseUrl: string;
+        googleBaseUrl: string;
+    };
+    app?: AppType;
+    appVersion?: number;
+    token?: string;
+    /**
+     * The host hands the token over after boot (it mints one for its own signed-in user): the client
+     * waits for it, rather than signing in anonymously first and again once it lands.
+     */
+    awaitsToken?: boolean;
+    /** The current user as the host fetched it for this boot, taken instead of `authenticate()`. */
+    bootUser?: Omit<User, "isAuthenticated"> | null;
+    /** The host's own app lookup failed with no token to drop: the viewer must sign in. */
+    hasAppLoadFailed?: boolean;
+    /** The dev server with no token stored: sign in, where a live app would render signed out. */
+    requiresSignIn?: boolean;
+    /**
+     * The host holds the app's routes until it has navigated to the page the app opens on (the
+     * builder's canvas boots on the app's root while it may still be loading its page list). Nothing
+     * renders meanwhile, so no page flashes and no page's data loads.
+     */
+    routesHeld?: boolean;
+    themeMode: ThemeMode;
+}
+/**
+ * How the host extends the tree, and what the tree tells it. Set once, before the tree renders. The
+ * layers render inside the app's own root, so they must use the same react-router, SDK and
+ * `@blocksdiy/blocks-client-sdk/app` modules the app does: a host that provides those modules to
+ * its bundles (as app-render does, on `window`) gets that for free.
+ */
+export interface BlocksHostExtensions {
+    /** Rendered inside the app's router, before the app: the host's own use of the router. */
+    RouterLayer?: ComponentType;
+    /** Wraps the app's routes, inside the SDK client: the host's own layer over the app. */
+    Shell?: ComponentType<{
+        children: ReactNode;
+    }>;
+    /**
+     * Shown where the viewer must sign in (an app the host could not load, an auth URL, the dev
+     * server without a token), in place of the tree's own login. `null`: the host keeps the viewer
+     * signed in, so the tree shows no sign-in screen, and an auth URL returns to the app's start.
+     */
+    SignIn?: ComponentType | null;
+    /** The routes the tree resolved, for naming the page in error reports. */
+    onRoutesResolved?: (routes: RouteObject[] | undefined) => void;
+    /** The app's code is in and the app is on its page: once per load of the code. */
+    onReady?: () => void;
+    /** The app is on a page: the page's id (a route's id, a legacy page's) and its query. */
+    onPageChange?: (page: {
+        pageId: string;
+        searchParams: string;
+    }) => void;
+    /** A URL the app has no page for. */
+    onMissingPage?: (missing: {
+        url: string;
+        pages: {
+            id: string;
+            name: string;
+        }[];
+    }) => void;
+    /** A render error the tree caught (it renders nothing in its place), or code with no page to show. */
+    onAppError?: (report: {
+        error: Error;
+        componentStack?: string;
+        blockId?: string;
+    }) => void;
+    /** The app asked to sign out (`/auth/logout`) where the host keeps the viewer signed in. */
+    onSignOut?: () => void;
+}
+export declare const THEME_MODE_STORAGE_KEY = "app-theme-mode";
+/** The theme mode to start from: the viewer's stored choice, else the app's default. */
+export declare const initialThemeMode: (app: AppType | undefined) => ThemeMode;
+export declare const setBlocksHost: (next: BlocksHostState) => void;
+export declare const updateBlocksHost: (patch: Partial<BlocksHostState>) => void;
+export declare const getBlocksHostState: () => BlocksHostState | null;
+export declare const setBlocksHostExtensions: (next: BlocksHostExtensions) => void;
+export declare const getBlocksHostExtensions: () => BlocksHostExtensions;
+/** The viewer's choice, or the host's: stored, applied to the document, and pushed to the tree. */
+export declare const setThemeMode: (themeMode: ThemeMode) => void;
+/**
+ * A value derived from the host state: the component re-renders only when that value changes. The
+ * value must stay the same between updates that don't change it: a field, or a primitive.
+ */
+export declare const useBlocksHostSelector: <T>(select: (state: BlocksHostState) => T) => T;
+/** One field of the host state, re-rendering only when that field changes. */
+export declare const useBlocksHostField: <K extends keyof BlocksHostState>(key: K) => BlocksHostState[K];
+/** Tests only: forget the host between cases. */
+export declare const resetBlocksHostForTests: () => void;
+//# sourceMappingURL=host.d.ts.map