@backmatter/core 0.0.19 → 0.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/core",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "description": "Experimental Backmatter SDK. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {

package/src/config.ts

@@ -63,6 +63,8 @@ export const DEFAULT_DIRS: Required<BackmatterDirs> = {
 };
 export const DEFAULT_LOCALE = "en";
 export const CLOUD_API_URL = "https://api.backmatter.app";
+export const CLOUD_DASHBOARD_URL = "https://dash.backmatter.app";
+export const LOCAL_DASHBOARD_URL = "http://localhost:5173";
 
 function withHttps(url: string): string {
   if (url.startsWith("http://") || url.startsWith("https://")) return url;
@@ -88,6 +90,29 @@ export function isDeployedHost(env: Record<string, string | undefined>): boolean
   );
 }
 
+/**
+ * Dashboard origin the dev bar frames.
+ * Explicit URL, else `BACKMATTER_DASHBOARD_URL`, else the cloud dashboard on a
+ * deployed host, else the local Vite app. A loopback URL in `.env` is ignored
+ * during a local `next build`, so the built site does not keep pointing at the laptop.
+ */
+export function resolveDashboardUrl(
+  explicit?: string,
+  env: Record<string, string | undefined> = envOf(),
+): string {
+  const fromProp = explicit?.trim();
+  const fromEnv = fromProp ? undefined : env.BACKMATTER_DASHBOARD_URL?.trim();
+  const candidate = fromProp || fromEnv || "";
+  const ignoreDevLoopback =
+    !fromProp &&
+    Boolean(candidate && isLoopbackApiUrl(candidate)) &&
+    env.NEXT_PHASE === "phase-production-build" &&
+    !onPlatformDeploy(env);
+  if (candidate && !ignoreDevLoopback) return stripTrailingSlash(candidate);
+  if (isDeployedHost(env)) return CLOUD_DASHBOARD_URL;
+  return LOCAL_DASHBOARD_URL;
+}
+
 /** DevBar /me origin: explicit, else env, else cloud API on a deployed host. */
 export function resolveDevBarApiUrl(
   explicit: string | undefined,

package/src/enter.ts

@@ -0,0 +1,68 @@
+// packages/core/src/enter.ts
+// The dashboard is the identity provider. A site that needs a session sends
+// the browser top-level to `{dashboard}/enter`, which mints a ticket from the
+// first-party cookie and returns to `{site}/api/backmatter/preview?ticket=`.
+
+export const ENTER_PATH = "/enter";
+export const PREVIEW_ENTRY_PATH = "/api/backmatter/preview";
+
+export type EnterRequest = {
+  workspaceId: string;
+  /** Absolute URL on the site to land on after the session is set. */
+  returnUrl: string;
+};
+
+export function studioEnterUrl(dashboardUrl: string, req: EnterRequest): string {
+  const url = new URL(ENTER_PATH, dashboardUrl.replace(/\/+$/, "") + "/");
+  url.searchParams.set("workspace", req.workspaceId);
+  url.searchParams.set("return", req.returnUrl);
+  return url.toString();
+}
+
+export function parseEnterSearch(search: string): EnterRequest | null {
+  const params = new URLSearchParams(search);
+  const workspaceId = params.get("workspace")?.trim() ?? "";
+  const returnUrl = params.get("return")?.trim() ?? "";
+  if (!workspaceId || !returnUrl) return null;
+  return { workspaceId, returnUrl };
+}
+
+export type EnterTarget = {
+  /** Site origin the ticket is for. Must be one of the workspace's `siteUrls`. */
+  origin: string;
+  /** Same-origin path, with search, the ticket redirects to. */
+  redirect: string;
+};
+
+/**
+ * Resolve where a return URL points, allowing only origins the workspace has
+ * declared. Returns null for a foreign origin, a bad URL, or a non-http scheme.
+ */
+export function resolveEnterTarget(returnUrl: string, siteUrls: readonly string[]): EnterTarget | null {
+  let url: URL;
+  try {
+    url = new URL(returnUrl);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+  const allowed = new Set(
+    siteUrls
+      .map((raw) => {
+        try {
+          return new URL(raw).origin;
+        } catch {
+          return null;
+        }
+      })
+      .filter((o): o is string => Boolean(o)),
+  );
+  if (!allowed.has(url.origin)) return null;
+  const redirect = `${url.pathname}${url.search}` || "/";
+  return { origin: url.origin, redirect };
+}
+
+/** The URL the dashboard sends the browser to once it holds a ticket. */
+export function previewEntryUrl(origin: string, ticket: string): string {
+  return `${origin}${PREVIEW_ENTRY_PATH}?ticket=${encodeURIComponent(ticket)}`;
+}

package/src/fields.ts

@@ -28,6 +28,12 @@ export type FieldDef<
   object?: string;
   /** Nested fields for object/array (inline or copied from defineObject). */
   fields?: Record<string, FieldDef>;
+  /**
+   * Name of the Studio input that edits this field, e.g. `"color"`. The site's
+   * `defineStudio({ fields })` maps names to components; unknown names fall
+   * back to the default input for the kind.
+   */
+  input?: string;
 };
 
 export type FieldSnapshot = {
@@ -36,20 +42,22 @@ export type FieldSnapshot = {
   relationTo?: string;
   object?: string;
   fields?: Record<string, FieldSnapshot>;
+  input?: string;
 };
 
 type ObjectLike = { name: string; fields: Record<string, FieldDef> };
 
-type Opts<R extends boolean> = { required?: R };
+type Opts<R extends boolean> = { required?: R; input?: string };
 
 function base<K extends FieldKind, R extends boolean, To extends string>(
   kind: K,
-  opts?: { required?: R; relationTo?: To },
+  opts?: { required?: R; relationTo?: To; input?: string },
 ): FieldDef<K, R, To> {
   return {
     kind,
     ...(opts?.required ? { required: opts.required } : {}),
     ...(opts?.relationTo ? { relationTo: opts.relationTo } : {}),
+    ...(opts?.input ? { input: opts.input } : {}),
   } as FieldDef<K, R, To>;
 }
 
@@ -59,10 +67,11 @@ function composite<K extends "object" | "array", R extends boolean>(
   opts?: Opts<R>,
 ): FieldDef<K, R> {
   const required = opts?.required ? { required: opts.required as R } : {};
+  const input = opts?.input ? { input: opts.input } : {};
   if (typeof def === "string") {
-    return { kind, object: def, ...required };
+    return { kind, object: def, ...required, ...input };
   }
-  return { kind, object: def.name, fields: def.fields, ...required };
+  return { kind, object: def.name, fields: def.fields, ...required, ...input };
 }
 
 export const field = {
@@ -86,6 +95,7 @@ export function serializeField(def: FieldDef): FieldSnapshot {
     ...(def.required ? { required: true } : {}),
     ...(def.relationTo ? { relationTo: def.relationTo } : {}),
     ...(def.object ? { object: def.object } : {}),
+    ...(def.input ? { input: def.input } : {}),
   };
   if (def.fields) {
     const fields: Record<string, FieldSnapshot> = {};
@@ -125,6 +135,9 @@ export function parseFieldSnapshot(input: unknown): FieldSnapshot {
   if (typeof value.object === "string" && value.object.length > 0) {
     snap.object = value.object;
   }
+  if (typeof value.input === "string" && value.input.length > 0) {
+    snap.input = value.input;
+  }
   if (value.fields && typeof value.fields === "object" && !Array.isArray(value.fields)) {
     const fields: Record<string, FieldSnapshot> = {};
     for (const [name, nested] of Object.entries(value.fields as Record<string, unknown>)) {

package/src/index.ts

@@ -58,9 +58,12 @@ export {
   detectSiteUrl,
   isDeployedHost,
   resolveDevBarApiUrl,
+  resolveDashboardUrl,
   DEFAULT_DIRS,
   DEFAULT_LOCALE,
   CLOUD_API_URL,
+  CLOUD_DASHBOARD_URL,
+  LOCAL_DASHBOARD_URL,
 } from "./config";
 
 export type { RouteMatch, RouteModel, MatchRouteOptions } from "./routes";
@@ -165,3 +168,14 @@ export {
   revalidateTagsForCommit,
   revalidateUrl,
 } from "./content-committed";
+
+export {
+  ENTER_PATH,
+  PREVIEW_ENTRY_PATH,
+  parseEnterSearch,
+  previewEntryUrl,
+  resolveEnterTarget,
+  studioEnterUrl,
+  type EnterRequest,
+  type EnterTarget,
+} from "./enter";

package/src/node/cli.ts

@@ -359,6 +359,44 @@ export const { GET, POST, PUT, DELETE } = createCmsProxy(cms);
 `;
 }
 
+const STUDIO_DIR = path.join("(backmatter)", "backmatter");
+
+function renderStudioLayout(): string {
+  return `// app/(backmatter)/backmatter/layout.tsx — own root layout so the site's
+// header, footer, fonts and global CSS do not wrap the Studio.
+export { StudioLayout as default } from "@backmatter/next/studio";
+`;
+}
+
+function renderStudioPage(studioImport: string): string {
+  return `// app/(backmatter)/backmatter/[[...path]]/page.tsx — the Backmatter Studio,
+// mounted on this site. Editors sign in at the dashboard; the Studio talks to
+// /api/backmatter/cms on this origin with the site session cookie.
+import { createStudioPage } from "@backmatter/next/studio";
+import { cms } from "${REGISTRY_SPECIFIER}";
+import studio from "${studioImport}";
+
+export default createStudioPage(cms, { studio });
+`;
+}
+
+function renderStudioDefinition(): string {
+  return `// backmatter.studio.tsx — how the Studio looks and which inputs it uses on
+// this site. A "use client" module: field inputs and block previews are
+// ordinary React components bundled by the site.
+"use client";
+
+import { defineStudio } from "@backmatter/studio/define";
+
+export default defineStudio({
+  // theme: { accent: "#1d4ed8" },
+  // fields: { color: ColorInput },            // field.text({ input: "color" })
+  // blocks: { Hero: { preview: HeroPreview } },
+  menu: [{ label: "Open site", href: "/" }],
+});
+`;
+}
+
 function renderRevalidateRoute(): string {
   return `// api/backmatter/revalidate/route.ts — content.committed from the BACKMATTER server.
 import { createRevalidateRoute } from "@backmatter/next/revalidate";
@@ -433,6 +471,37 @@ export async function runInit(args: CliArgs): Promise<string[]> {
       notes.push(`kept existing ${path.join(appDir, "api/backmatter/preview/route.ts")}`);
     }
 
+    const studioDefinition = path.join(root, "backmatter.studio.tsx");
+    if (!existsSync(studioDefinition)) {
+      await writeFile(studioDefinition, renderStudioDefinition());
+      notes.push("wrote backmatter.studio.tsx");
+    } else {
+      notes.push("kept existing backmatter.studio.tsx");
+    }
+
+    const studioDir = path.join(root, appDir, STUDIO_DIR);
+    const studioLayout = path.join(studioDir, "layout.tsx");
+    if (!existsSync(studioLayout)) {
+      await mkdir(studioDir, { recursive: true });
+      await writeFile(studioLayout, renderStudioLayout());
+      notes.push(`wrote ${path.join(appDir, STUDIO_DIR, "layout.tsx")}`);
+    } else {
+      notes.push(`kept existing ${path.join(appDir, STUDIO_DIR, "layout.tsx")}`);
+    }
+    const studioPageDir = path.join(studioDir, "[[...path]]");
+    const studioPage = path.join(studioPageDir, "page.tsx");
+    if (!existsSync(studioPage)) {
+      await mkdir(studioPageDir, { recursive: true });
+      const studioImport = path
+        .relative(studioPageDir, path.join(root, "backmatter.studio"))
+        .split(path.sep)
+        .join("/");
+      await writeFile(studioPage, renderStudioPage(studioImport));
+      notes.push(`wrote ${path.join(appDir, STUDIO_DIR, "[[...path]]", "page.tsx")}`);
+    } else {
+      notes.push(`kept existing ${path.join(appDir, STUDIO_DIR, "[[...path]]", "page.tsx")}`);
+    }
+
     const proxyFile = path.join(root, "proxy.ts");
     const srcProxy = path.join(root, "src", "proxy.ts");
     const middlewareFile = path.join(root, "middleware.ts");

package/src/preview.ts

@@ -67,6 +67,16 @@ export type DevMode = {
   tree?: string;
 };
 
+/** Why the host session endpoint refused to open the bar. */
+export type HostSessionReason = "invalid" | "anonymous" | "unavailable";
+
+export type HostPreviewSession = {
+  enabled: boolean;
+  branch?: string;
+  tree?: string;
+  reason?: HostSessionReason;
+};
+
 export function resolveDevMode(session: {
   enabled: boolean;
   branch?: string;
@@ -79,28 +89,32 @@ export function resolveDevMode(session: {
   };
 }
 
-export async function fetchHostPreviewSession(
-  origin = "",
-): Promise<{ enabled: boolean; branch?: string; tree?: string }> {
+function hostSessionReason(value: unknown): HostSessionReason {
+  if (value === "invalid" || value === "unavailable") return value;
+  return "anonymous";
+}
+
+export async function fetchHostPreviewSession(origin = ""): Promise<HostPreviewSession> {
   try {
     const res = await fetch(`${origin.replace(/\/$/, "")}/api/backmatter/preview?session=1`, {
       credentials: "same-origin",
       cache: "no-store",
     });
-    if (!res.ok) return { enabled: false };
+    if (!res.ok) return { enabled: false, reason: "unavailable" };
     const data = (await res.json()) as {
       mode?: string;
       branch?: string;
       tree?: string;
+      reason?: unknown;
     };
-    if (data.mode !== "preview") return { enabled: false };
+    if (data.mode !== "preview") return { enabled: false, reason: hostSessionReason(data.reason) };
     return {
       enabled: true,
       ...(typeof data.branch === "string" && data.branch ? { branch: data.branch } : {}),
       ...(typeof data.tree === "string" && data.tree ? { tree: data.tree } : {}),
     };
   } catch {
-    return { enabled: false };
+    return { enabled: false, reason: "unavailable" };
   }
 }