@blocksdiy/blocks-client-sdk 1.24.2 → 1.25.1

package/README.md

@@ -1 +1,33 @@
 # blocks-client-sdk
+
+`@blocksdiy/blocks-client-sdk`: what a Blocks app uses to work with the platform, wherever the app runs (Blocks' hosting, `pnpm dev`, the builder's sandbox, or a host of your own).
+
+| Entry                                    | What it holds                                                                                                           |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `@blocksdiy/blocks-client-sdk/clientSdk` | `ClientSdk`: entities, actions, files, users.                                                                           |
+| `@blocksdiy/blocks-client-sdk/reactSdk`  | React hooks over the client, and the navigation helpers (`getRouteUrl`, `getLoginUrl`, `logOut`); needs `react-router`. |
+| `@blocksdiy/blocks-client-sdk/app`       | `BlocksApp`, the app's React tree, and the host contract a page hosting Blocks apps implements; needs `react-router`.   |
+| `@blocksdiy/blocks-client-sdk/page`      | Page types for legacy pages-mode apps.                                                                                  |
+| `@blocksdiy/blocks-client-sdk`           | Everything from `clientSdk` and `reactSdk`.                                                                             |
+
+## The app entry
+
+An app's `src/main.tsx` renders `BlocksApp` with the modules it globbed. `BlocksApp` holds what any Blocks app needs wherever it runs: the router, the sign-in screen, the SDK client, the app's routes (file-system routes, or legacy pages) with error boundaries, and the default 404 and loading screens. On the dev server it hosts itself (`window.__BLOCKS_DEV__`, `src/app/dev-server/`).
+
+What only Blocks' own hosting needs (the builder canvas's tools, the mobile app's wiring) is not here: it lives in `apps/app-render`, which plugs it in through the host contract (`src/app/host.ts`):
+
+- **state** the tree reads, kept current by the host: `setBlocksHost`, `updateBlocksHost`;
+- **extensions**, set once before rendering (`setBlocksHostExtensions`): a `RouterLayer` inside the app's router, a `Shell` around its routes, a `SignIn` screen in place of the tree's login, and the reports `onReady`, `onPageChange`, `onMissingPage`, `onAppError`, `onSignOut` and `onRoutesResolved`.
+
+| Folder (`src/app/`) | What it holds                                                                            |
+| ------------------- | ---------------------------------------------------------------------------------------- |
+| `BlocksApp.tsx`     | The tree: router, the host's router layer, sign-in, client, routes.                      |
+| `AppRoutes.tsx`     | The app's routes in either mode, with the reports, error boundaries, 404 and loading.    |
+| `host.ts`           | The host contract.                                                                       |
+| `SdkProvider.tsx`   | The SDK client around the app's routes, on the host's token and user.                    |
+| `types.ts`          | The app and route types the contract and the shapes share.                               |
+| `app-shape/`        | What an app's code amounts to: a bundle or globbed modules, shaped into routes or pages. |
+| `sign-in/`          | The login and its platform calls.                                                        |
+| `dev-server/`       | Self-hosting on the dev server.                                                          |
+| `ui/`               | The tree's own screens' styles (shadcn's look, on the app's tokens) and icons.           |
+| `hooks/`            | The tree's own hooks: scroll to the top on a page change.                                |

package/dist/Navigation.d.ts

@@ -0,0 +1,40 @@
+import type { PageConfig } from "./Page.js";
+/**
+ * Navigation and session helpers an app's code calls, exported with the React SDK (`reactSdk` and the
+ * package root): they need react-router (a peer, present in every app) and the browser.
+ */
+/**
+ * For calls in migrated apps: `getPageUrl('Dashboard')` → `/Dashboard`, the URL of that page's
+ * route.
+ *
+ * @deprecated Navigate with real URLs or {@link getRouteUrl}.
+ */
+export declare function getPageUrl(page: PageConfig | string, searchParams?: Record<string, string>): string;
+/**
+ * Builds a URL for a file-system route (`src/routes/`), filling dynamic params.
+ *
+ * Pass the route's URL pattern (what the file path under `src/routes/`
+ * resolves to), params for any `:param` segments, and optional search params.
+ *
+ * @example
+ * ```ts
+ * // src/routes/products/[productId].tsx
+ * getRouteUrl('products/:productId', { productId: '123' });
+ * // => "/products/123"
+ *
+ * getRouteUrl('/orders', undefined, { status: 'open' });
+ * // => "/orders?status=open"
+ * ```
+ */
+export declare function getRouteUrl(routePath: string, params?: Record<string, string>, searchParams?: Record<string, string>): string;
+/**
+ * Generates a URL for the login page
+ *
+ * @returns {string} The URL for the login page
+ */
+export declare function getLoginUrl(): string;
+/**
+ * Logs out the user by removing the token from localStorage and reloading the page
+ */
+export declare function logOut(): void;
+//# sourceMappingURL=Navigation.d.ts.map

package/dist/Navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Navigation.d.ts","sourceRoot":"","sources":["../src/Navigation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC;;;GAGG;AAEH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,YAAY,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,UAqB9F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACnC,YAAY,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,UAM1C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,WAE1B;AAED;;GAEG;AACH,wBAAgB,MAAM,SAGrB"}

package/dist/Navigation.js

@@ -0,0 +1,66 @@
+import { generatePath } from "react-router";
+import { tokenStorageKey } from "./dev-config.js";
+/**
+ * Navigation and session helpers an app's code calls, exported with the React SDK (`reactSdk` and the
+ * package root): they need react-router (a peer, present in every app) and the browser.
+ */
+/**
+ * For calls in migrated apps: `getPageUrl('Dashboard')` → `/Dashboard`, the URL of that page's
+ * route.
+ *
+ * @deprecated Navigate with real URLs or {@link getRouteUrl}.
+ */
+export function getPageUrl(page, searchParams = {}) {
+    const appId = window.appId;
+    if (!appId) {
+        return "";
+    }
+    const searchParamsString = new URLSearchParams(searchParams).toString();
+    const { pathname: currentPath } = window.location;
+    const pageBlockId = typeof page === "string" ? page : page.pageBlockId;
+    const pageName = typeof page === "string" ? page : page.pageName;
+    if (currentPath.startsWith("/app/")) {
+        return `/app/${pageBlockId}${searchParamsString ? `?${searchParamsString}` : ""}`;
+    }
+    if (currentPath.startsWith("/apps/")) {
+        return `/apps/${appId}/design/pages/${pageBlockId}${searchParamsString ? `?${searchParamsString}` : ""}`;
+    }
+    return `/${pageName || pageBlockId}${searchParamsString ? `?${searchParamsString}` : ""}`;
+}
+/**
+ * Builds a URL for a file-system route (`src/routes/`), filling dynamic params.
+ *
+ * Pass the route's URL pattern (what the file path under `src/routes/`
+ * resolves to), params for any `:param` segments, and optional search params.
+ *
+ * @example
+ * ```ts
+ * // src/routes/products/[productId].tsx
+ * getRouteUrl('products/:productId', { productId: '123' });
+ * // => "/products/123"
+ *
+ * getRouteUrl('/orders', undefined, { status: 'open' });
+ * // => "/orders?status=open"
+ * ```
+ */
+export function getRouteUrl(routePath, params = {}, searchParams = {}) {
+    const normalizedPath = routePath.startsWith("/") ? routePath : `/${routePath}`;
+    const pathname = generatePath(normalizedPath, params);
+    const searchParamsString = new URLSearchParams(searchParams).toString();
+    return `${pathname}${searchParamsString ? `?${searchParamsString}` : ""}`;
+}
+/**
+ * Generates a URL for the login page
+ *
+ * @returns {string} The URL for the login page
+ */
+export function getLoginUrl() {
+    return `/auth/login`;
+}
+/**
+ * Logs out the user by removing the token from localStorage and reloading the page
+ */
+export function logOut() {
+    localStorage.removeItem(tokenStorageKey());
+    window.location.href = "/auth/logout";
+}

package/dist/ReactClientSdk.d.ts

@@ -11,6 +11,7 @@ import type { Integration } from "./Integration.js";
 import type { PageConfig } from "./Page.js";
 import { canManageUsers } from "./Permission.js";
 export { canManageUsers };
+export { getLoginUrl, getPageUrl, getRouteUrl, logOut } from "./Navigation.js";
 export type { AppUserPermission } from "./Permission.js";
 export declare class ReactClientSdk extends ClientSdk {
 }

package/dist/ReactClientSdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReactClientSdk.d.ts","sourceRoot":"","sources":["../src/ReactClientSdk.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"ReactClientSdk.d.ts","sourceRoot":"","sources":["../src/ReactClientSdk.tsx"],"names":[],"mappings":"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"}

package/dist/ReactClientSdk.jsx

@@ -14,6 +14,7 @@ import { createEntityLiveSync } from "./EntityLiveSync.js";
 import { isEntityQuery } from "./EntityQuery.js";
 import { canManageUsers } from "./Permission.js";
 export { canManageUsers };
+export { getLoginUrl, getPageUrl, getRouteUrl, logOut } from "./Navigation.js";
 export class ReactClientSdk extends ClientSdk {
 }
 const CURRENT_USER_QUERY_KEY = "currentUser";

package/dist/app/AppRoutes.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+/**
+ * The app's routes, in either mode, inside the host's `Shell` when it has one. Stays mounted while
+ * a shell swaps the routes out (the builder's chat-component preview), so what it reports once per
+ * load of the code is reported once.
+ */
+export declare const AppRoutes: () => React.JSX.Element | null;
+//# sourceMappingURL=AppRoutes.d.ts.map

package/dist/app/AppRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppRoutes.d.ts","sourceRoot":"","sources":["../../src/app/AppRoutes.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA+E,MAAM,OAAO,CAAC;AA0RpG;;;;GAIG;AACH,eAAO,MAAM,SAAS,gCAmCrB,CAAC"}

package/dist/app/AppRoutes.jsx

@@ -0,0 +1,222 @@
+import React, { useEffect, useInsertionEffect, useMemo, useState } from "react";
+import { ErrorBoundary } from "react-error-boundary";
+import { Link, matchRoutes, Navigate, Outlet, Route, Routes, useLocation, useRoutes, useSearchParams, } from "react-router";
+import { useAppShape } from "./app-shape/use-app-shape.js";
+import { useScrollToTopOnPageChange } from "./hooks/use-scroll-to-top-on-page-change.js";
+import { getBlocksHostExtensions, useBlocksHostField, useBlocksHostSelector } from "./host.js";
+import { isAuthUrl } from "./sign-in/auth-url.js";
+import { MissingPageIcon, SpinnerIcon } from "./ui/icons";
+import { ensureUiStyles } from "./ui/ui-styles.js";
+/**
+ * Report-only error boundary: renders nothing in place of what threw, and tells the host, which owns
+ * the error's display. Told from an effect after the commit that caught it, not from `onError`: a
+ * host that clears its errors when the app is ready (the builder) hears the ready report of that
+ * commit first, and this error after it.
+ */
+const ReportingBoundary = ({ blockId, resetKeys, children, }) => {
+    const [report, setReport] = useState(null);
+    useEffect(() => {
+        if (report) {
+            getBlocksHostExtensions().onAppError?.(report);
+        }
+    }, [report]);
+    return (<ErrorBoundary fallback={null} resetKeys={resetKeys} onReset={() => setReport(null)} onError={(error, info) => setReport({
+            error: error instanceof Error ? error : new Error(String(error)),
+            componentStack: info.componentStack ?? "",
+            blockId,
+        })}>
+      {children}
+    </ErrorBoundary>);
+};
+/**
+ * An auth URL where the host keeps the viewer signed in (the only way one reaches the routes): the
+ * host hears a sign-out, and the app goes back to its start.
+ */
+const AuthRedirect = () => {
+    const location = useLocation();
+    useEffect(() => {
+        if (location.pathname.startsWith("/auth/logout")) {
+            getBlocksHostExtensions().onSignOut?.();
+        }
+    }, [location.pathname]);
+    return <Navigate to={{ pathname: "/", search: location.search }} replace/>;
+};
+/** The boundary around one page or layout, naming it in the report. Resets when the block changes. */
+const BlockErrorBoundary = ({ blockId, children }) => (<ReportingBoundary blockId={blockId} resetKeys={[blockId]}>
+    {children}
+  </ReportingBoundary>);
+/**
+ * Automation (the builder's cover capture, browser checks, end-to-end tests) waits for this flag:
+ * set once the app's page is mounted, inside the boundary, so a render crash unmounts it and the
+ * cleanup clears the flag.
+ */
+const AppReadyFlag = () => {
+    useEffect(() => {
+        const page = window;
+        page.__blocksAppReady = true;
+        return () => {
+            page.__blocksAppReady = false;
+        };
+    }, []);
+    return null;
+};
+const Page = ({ pageBlockId, Component }) => {
+    const [searchParams] = useSearchParams();
+    useEffect(() => {
+        getBlocksHostExtensions().onPageChange?.({ pageId: pageBlockId, searchParams: searchParams.toString() });
+    }, [pageBlockId, searchParams]);
+    return (<BlockErrorBoundary blockId={pageBlockId}>
+      <Component />
+      <AppReadyFlag />
+    </BlockErrorBoundary>);
+};
+const Layout = () => {
+    const { layout } = useAppShape();
+    if (!layout) {
+        return <Outlet />;
+    }
+    const LayoutComponent = layout.component;
+    return (<BlockErrorBoundary blockId={layout.id}>
+      <LayoutComponent>
+        <Outlet />
+      </LayoutComponent>
+    </BlockErrorBoundary>);
+};
+/**
+ * Routes mode: the app's file-system route tree, through useRoutes. Route components render bare;
+ * the cross-cutting concerns live at the edges: one error boundary reports render errors, and one
+ * location-driven effect reports the matched route (so a host following the app, like the
+ * builder's canvas, follows in-app navigation). Unmatched URLs render the default 404
+ * (MissingPageFallback) unless the app ships its own `not-found.tsx` or splat, which matches first.
+ */
+const RoutesTree = ({ routes }) => {
+    const { componentsLoadedAt } = useAppShape();
+    const location = useLocation();
+    const routeObjects = useMemo(() => {
+        // The tree IS a RouteObject tree: useRoutes renders the `Component` field natively (the extra
+        // `id`/`name` metadata is ignored). The cast bridges the nominal types; nothing is transformed.
+        const children = [...routes.routes];
+        // Default 404: an app-defined catch-all (not-found.tsx or a root splat) sits earlier in the
+        // array and wins; otherwise unmatched URLs render the fallback and report up. "/" included:
+        // apps own their landing page via routes/index.tsx (the migration generates one for legacy apps).
+        children.push({ path: "*", element: <MissingPageFallback /> });
+        return [{ id: "root", Component: routes.root?.Component ?? Outlet, children }];
+    }, [routes]);
+    const isAuthPath = isAuthUrl(location.pathname);
+    // The deepest matched APP route (ids starting with "routes/").
+    const matchedRouteId = useMemo(() => {
+        const matches = matchRoutes(routeObjects, location) ?? [];
+        return [...matches].reverse().find((match) => match.route.id?.startsWith("routes/"))?.route.id;
+    }, [routeObjects, location]);
+    // Every location is reported, the host's own first navigation included: the builder treats a
+    // report of the page it selected as a no-op, and a `:param` page's concrete ancestor as the parked
+    // boot it is (never a navigation away).
+    useEffect(() => {
+        if (!matchedRouteId || isAuthPath) {
+            return;
+        }
+        getBlocksHostExtensions().onPageChange?.({
+            pageId: matchedRouteId,
+            searchParams: location.search.replace(/^\?/, ""),
+        });
+    }, [matchedRouteId, location.search, location.key, isAuthPath]);
+    const element = useRoutes(routeObjects);
+    if (isAuthPath) {
+        return <AuthRedirect />;
+    }
+    return (
+    // Names the matched route; resets when the user navigates or the app recompiles.
+    <ReportingBoundary blockId={matchedRouteId} resetKeys={[location.pathname, componentsLoadedAt]}>
+      {/* key remounts the whole app tree after a recompile so new code takes over cleanly */}
+      <React.Fragment key={componentsLoadedAt}>{element}</React.Fragment>
+      <AppReadyFlag />
+    </ReportingBoundary>);
+};
+/**
+ * Pages mode (legacy apps): each page at its name and its id, inside the app's layout, landing on
+ * the default page; before the pages arrive, a loading screen.
+ */
+const PagesRoutes = ({ pages, defaultPage }) => {
+    const { componentsLoadedAt } = useAppShape();
+    const page = ({ id, component }) => (<Page pageBlockId={id} Component={component} key={`${id}-${componentsLoadedAt}`}/>);
+    return (<Routes>
+      <Route path="/" element={<Layout key={`layout-${componentsLoadedAt}`}/>}>
+        {defaultPage && <Route index element={page(defaultPage)}/>}
+        {pages.length > 0 ? (<>
+            {pages.map((block) => (<Route key={block.id} path={`/${block.id}`} element={page(block)}/>))}
+            {pages.map((block) => block.name !== block.id ? <Route key={block.name} path={`/${block.name}`} element={page(block)}/> : null)}
+            <Route path="*" element={<MissingPageFallback />}/>
+          </>) : (<Route path="*" element={<LoadingScreen />}/>)}
+      </Route>
+      {defaultPage && <Route path="/auth/*" element={<AuthRedirect />}/>}
+    </Routes>);
+};
+/**
+ * The default 404 with its report, as shadcn's empty state on the app's tokens (`ui-styles.ts`).
+ * Renders inside the app's root layout, so it inherits the app's font and text color. Apps that want
+ * their own 404 ship `routes/not-found.tsx`, which matches before this route.
+ */
+const MissingPageFallback = () => {
+    const { pages } = useAppShape();
+    const location = useLocation();
+    useEffect(() => {
+        getBlocksHostExtensions().onMissingPage?.({
+            url: `${location.pathname}${location.search}`,
+            pages: pages.map(({ id, name }) => ({ id, name })),
+        });
+    }, [location, pages]);
+    useInsertionEffect(ensureUiStyles, []);
+    return (<div className="blocks-ui ui-empty">
+      <div className="ui-empty-header">
+        <div className="ui-icon-tile">
+          <MissingPageIcon />
+        </div>
+        <h1 className="ui-empty-title">Page not found</h1>
+        <p className="ui-empty-description">This page doesn't exist or has moved.</p>
+      </div>
+      <Link to="/" className="ui-button ui-button-outline">
+        Back to home
+      </Link>
+    </div>);
+};
+/** A legacy app's routes before its pages arrive. */
+const LoadingScreen = () => {
+    useInsertionEffect(ensureUiStyles, []);
+    return (<div role="status" className="blocks-ui ui-loading">
+      <SpinnerIcon className="ui-spinner"/>
+      Loading…
+    </div>);
+};
+/**
+ * The app's routes, in either mode, inside the host's `Shell` when it has one. Stays mounted while
+ * a shell swaps the routes out (the builder's chat-component preview), so what it reports once per
+ * load of the code is reported once.
+ */
+export const AppRoutes = () => {
+    const routesHeld = useBlocksHostField("routesHeld");
+    const defaultPageBlockId = useBlocksHostSelector((state) => state.app?.defaultPageBlockId);
+    const { pages, routes, componentsLoadedAt, defaultPageId } = useAppShape();
+    const landingPageId = defaultPageBlockId || defaultPageId;
+    const defaultPage = landingPageId
+        ? pages.find(({ id, name }) => id === landingPageId || name === landingPageId)
+        : [...pages].sort((a, b) => a.id.localeCompare(b.id))[0];
+    const { Shell } = getBlocksHostExtensions();
+    useScrollToTopOnPageChange();
+    // Once the app is on its page, not merely loaded: a host lifts its loading cover on this, and a
+    // bundle that lands while the host holds the routes would uncover an empty page.
+    useEffect(() => {
+        if (componentsLoadedAt && !routesHeld) {
+            getBlocksHostExtensions().onReady?.();
+        }
+    }, [componentsLoadedAt, routesHeld]);
+    // After `onReady`, so a host that clears its errors on ready keeps this one. Routes mode is exempt:
+    // `pages` only counts leaf route modules, so an app that so far has only layout files loaded fine
+    // (the catch-all renders).
+    useEffect(() => {
+        if (componentsLoadedAt && !routesHeld && !routes && pages.length === 0) {
+            getBlocksHostExtensions().onAppError?.({ error: new Error("Could not load the components") });
+        }
+    }, [componentsLoadedAt, routesHeld, pages, routes]);
+    const content = routesHeld ? null : routes ? (<RoutesTree routes={routes}/>) : (<PagesRoutes pages={pages} defaultPage={defaultPage}/>);
+    return Shell ? <Shell>{content}</Shell> : content;
+};

package/dist/app/BlocksApp.d.ts

@@ -0,0 +1,22 @@
+import React from "react";
+import { type CompiledBundle } from "./app-shape/bundle-shape.js";
+export interface BlocksAppProps {
+    /** A self-mounting app: the modules its `src/main.tsx` globbed (`routes/**` and `root.tsx`, or `pages/**` and `layout.tsx`, plus the chat renderer). */
+    modules?: Record<string, unknown>;
+    /** The host's import of a bundle that exports its routes (`window.compiler`). */
+    bundle?: CompiledBundle;
+    /**
+     * When the host finished importing `bundle`, or failed to: the tree remounts on a new stamp, so a
+     * recompile's code takes over cleanly. Passed with the bundle, so the two change in one render.
+     */
+    componentsLoadedAt?: number;
+}
+/**
+ * A Blocks app's React tree: the router, the sign-in screen where the viewer must sign in, the SDK
+ * client, and the app's routes with error boundaries and the default 404. One component for every
+ * way an app runs: rendered by the app's own `src/main.tsx` into the root it creates, by app-render
+ * around a bundle that exports its routes, and on the dev server, where it hosts itself. What the
+ * host knows and adds comes from the host contract (`host.ts`).
+ */
+export declare const BlocksApp: ({ modules, bundle, componentsLoadedAt }: BlocksAppProps) => React.JSX.Element;
+//# sourceMappingURL=BlocksApp.d.ts.map

package/dist/app/BlocksApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlocksApp.d.ts","sourceRoot":"","sources":["../../src/app/BlocksApp.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA0D,MAAM,OAAO,CAAC;AAG/E,OAAO,EAAiB,KAAK,cAAc,EAAqC,MAAM,0BAA0B,CAAC;AASjH,MAAM,WAAW,cAAc;IAC7B,wJAAwJ;IACxJ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,iFAAiF;IACjF,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAgCD;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,yCAAyC,cAAc,sBAoChF,CAAC"}

package/dist/app/BlocksApp.jsx

@@ -0,0 +1,73 @@
+import React, { useInsertionEffect, useMemo } from "react";
+import { BrowserRouter, useLocation } from "react-router";
+import { shapeFromBundle, shapeFromModules } from "./app-shape/bundle-shape.js";
+import { AppShapeContext } from "./app-shape/use-app-shape.js";
+import { AppRoutes } from "./AppRoutes";
+import { ensureSelfHost } from "./dev-server/bootstrap.js";
+import { getBlocksHostExtensions, useBlocksHostField, useBlocksHostSelector } from "./host.js";
+import { SdkProvider } from "./SdkProvider";
+import { isAuthUrl } from "./sign-in/auth-url.js";
+import { Login } from "./sign-in/Login";
+/**
+ * Where the viewer must sign in (an app the host could not load with no token to drop, the dev
+ * server without a token, an auth URL), the sign-in screen shows in the app's place: the tree's own
+ * login, or the host's.
+ */
+const SignInGate = ({ SignIn, children }) => {
+    const hasAppLoadFailed = useBlocksHostField("hasAppLoadFailed");
+    const requiresSignIn = useBlocksHostField("requiresSignIn");
+    const token = useBlocksHostField("token");
+    const { pathname } = useLocation();
+    return hasAppLoadFailed || (requiresSignIn && !token) || isAuthUrl(pathname) ? <SignIn /> : children;
+};
+const EMPTY_SHAPE = { pages: [], isEmpty: false };
+/**
+ * When a self-mounting bundle's modules arrived: a recompile renders new ones into the same root,
+ * and the tree remounts on the new stamp. Kept per modules object, not in component state, so it
+ * changes exactly when the modules do.
+ */
+const moduleStamps = new WeakMap();
+const stampOf = (modules) => {
+    let stamp = moduleStamps.get(modules);
+    if (stamp === undefined) {
+        stamp = Date.now();
+        moduleStamps.set(modules, stamp);
+    }
+    return stamp;
+};
+/**
+ * A Blocks app's React tree: the router, the sign-in screen where the viewer must sign in, the SDK
+ * client, and the app's routes with error boundaries and the default 404. One component for every
+ * way an app runs: rendered by the app's own `src/main.tsx` into the root it creates, by app-render
+ * around a bundle that exports its routes, and on the dev server, where it hosts itself. What the
+ * host knows and adds comes from the host contract (`host.ts`).
+ */
+export const BlocksApp = ({ modules, bundle, componentsLoadedAt }) => {
+    // The dev server renders with no host page: the app hosts itself (once; idempotent under StrictMode).
+    ensureSelfHost();
+    const { RouterLayer, SignIn = Login } = getBlocksHostExtensions();
+    const modulesLoadedAt = modules && stampOf(modules);
+    const appId = useBlocksHostSelector((state) => state.app?.id);
+    const shape = useMemo(() => {
+        if (modules) {
+            return { ...shapeFromModules(modules), componentsLoadedAt: modulesLoadedAt };
+        }
+        if (bundle || appId) {
+            return { ...shapeFromBundle(bundle, appId), componentsLoadedAt };
+        }
+        return { ...EMPTY_SHAPE, componentsLoadedAt: undefined };
+    }, [modules, bundle, appId, modulesLoadedAt, componentsLoadedAt]);
+    // Before the tree commits, so a crash on this very render is attributed to these routes.
+    useInsertionEffect(() => {
+        getBlocksHostExtensions().onRoutesResolved?.(shape.componentsLoadedAt ? shape.errorRoutes : undefined);
+    }, [shape]);
+    const app = (<SdkProvider>
+      <AppRoutes />
+    </SdkProvider>);
+    return (<BrowserRouter>
+      <AppShapeContext value={shape}>
+        {RouterLayer && <RouterLayer />}
+        {SignIn ? <SignInGate SignIn={SignIn}>{app}</SignInGate> : app}
+      </AppShapeContext>
+    </BrowserRouter>);
+};

package/dist/app/SdkProvider.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+/** The SDK client for the app, authenticated as the host says, with the theme mode the host holds. */
+export declare const SdkProvider: ({ children }: {
+    children: React.ReactNode;
+}) => React.JSX.Element | null;
+//# sourceMappingURL=SdkProvider.d.ts.map

package/dist/app/SdkProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SdkProvider.d.ts","sourceRoot":"","sources":["../../src/app/SdkProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA8B,MAAM,OAAO,CAAC;AAKnD,sGAAsG;AACtG,eAAO,MAAM,WAAW,GAAI,cAAc;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,6BA+CtE,CAAC"}

package/dist/app/SdkProvider.jsx

@@ -0,0 +1,45 @@
+import React, { useEffect, useState } from "react";
+import { ClientProvider, ReactClientSdk } from "../ReactClientSdk";
+import { setThemeMode, useBlocksHostField, useBlocksHostSelector } from "./host.js";
+/** The SDK client for the app, authenticated as the host says, with the theme mode the host holds. */
+export const SdkProvider = ({ children }) => {
+    const token = useBlocksHostField("token");
+    const appId = useBlocksHostSelector((state) => state.app?.id);
+    const bootUser = useBlocksHostField("bootUser");
+    const awaitsToken = useBlocksHostField("awaitsToken");
+    const themeMode = useBlocksHostField("themeMode");
+    const [client, setClient] = useState(null);
+    // A host that hands the token over after boot (the builder mints one for its own user) is waited
+    // for, rather than authenticating anonymously first and again once it lands, which would render
+    // the app signed out for a beat.
+    const isAwaitingToken = awaitsToken && !token;
+    useEffect(() => {
+        if (!appId || isAwaitingToken) {
+            return;
+        }
+        let isCurrent = true;
+        const newClient = new ReactClientSdk({
+            appId,
+            token,
+        });
+        // The host fetched the current user on the app for this boot: the same answer `authenticate()`
+        // would fetch, taken instead of asked for.
+        const authenticated = bootUser
+            ? Promise.resolve(newClient.setAuthenticatedUser(bootUser))
+            : newClient.authenticate();
+        authenticated.then(() => {
+            if (isCurrent) {
+                setClient(newClient);
+            }
+        });
+        return () => {
+            isCurrent = false;
+        };
+    }, [appId, token, isAwaitingToken, bootUser]);
+    if (!client) {
+        return null;
+    }
+    return (<ClientProvider client={client} themeMode={themeMode} setThemeMode={setThemeMode}>
+      {children}
+    </ClientProvider>);
+};

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

@@ -0,0 +1,54 @@
+import type { ComponentType } from "react";
+import type { RouteObject } from "react-router";
+import type { BlocksRoutesTree } from "../types.js";
+/** A page (or the legacy layout) as the tree routes it. */
+export interface CodeBlock {
+    id: string;
+    name: string;
+    component: ComponentType;
+}
+/** What an app's code amounts to, whichever way it arrived. */
+export interface AppShape {
+    /** Present for routes-mode apps (file-system routing); legacy bundles leave it undefined. */
+    routes?: BlocksRoutesTree;
+    /** Legacy: one entry per page. Routes mode: the leaf routes, for missing-page reports. */
+    pages: CodeBlock[];
+    /** Legacy: the app's `AppLayout`. */
+    layout?: CodeBlock;
+    /**
+     * The app's chat-component renderer, when it has one: the module of the agent-chat item
+     * (`components/ui/agent-chat-code-component.tsx`, a bundle's `__agentChatCodeComponent`), as
+     * exported. What it renders is the host's to know.
+     */
+    chatComponentRenderer?: unknown;
+    /** The routes for error attribution, as the tree reports them to the host. */
+    errorRoutes?: RouteObject[];
+    /** Nothing threw, yet there is no page to show: reported, since a failed import is told apart. */
+    isEmpty: boolean;
+    /** A pages-mode app's landing page where the host names none (the dev server). */
+    defaultPageId?: string;
+}
+/** The module `window.compiler` holds once a compiled bundle has been imported. */
+export interface CompiledBundle {
+    [name: string]: unknown;
+    __blocksRoutes?: BlocksRoutesTree;
+    __agentChatCodeComponent?: unknown;
+    /** Legacy: the layout, shaped like a page (`{ id: "AppLayout", name, component }`). */
+    AppLayout?: CodeBlock;
+}
+/**
+ * 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 declare const shapeFromBundle: (bundle: CompiledBundle | undefined, appId: string | undefined) => AppShape;
+/**
+ * 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 declare const shapeFromModules: (modules: Record<string, unknown>) => AppShape;
+//# sourceMappingURL=bundle-shape.d.ts.map