@backmatter/core 0.0.20 → 0.0.22

package/package.json

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

package/src/config.ts

@@ -3,6 +3,12 @@
 // here; they are discovered from the `models/` folder.
 import { detectGitBranch } from "./sync-schema";
 
+/** Options for `<DevBar />` on the host site. */
+export type DevBarHostConfig = {
+  /** Draw a viewport ring and top pill while the site session is in preview. */
+  previewFrame?: boolean;
+};
+
 export type BackmatterDirs = {
   /** Folder with one `defineModel` default export per file. Default: "models". */
   models?: string;
@@ -45,6 +51,7 @@ export type BackmatterConfig = {
   /** Locale used by routes without a `{locale}` placeholder. Default: "en". */
   defaultLocale?: string;
   dirs?: BackmatterDirs;
+  devBar?: DevBarHostConfig;
 };
 
 export type ResolvedConfig = Omit<BackmatterConfig, "dirs" | "defaultLocale"> & {
@@ -211,6 +218,7 @@ export function resolveConfig(
     siteRoot: config.siteRoot,
     locales: config.locales,
     defaultLocale: config.defaultLocale ?? DEFAULT_LOCALE,
+    devBar: config.devBar,
     dirs: {
       models: config.dirs?.models ?? DEFAULT_DIRS.models,
       blocks: config.dirs?.blocks ?? DEFAULT_DIRS.blocks,

package/src/index.ts

@@ -51,7 +51,7 @@ export { defineSource } from "./source";
 export type { DocFormat } from "./doc-format";
 export { modelFormat, parseDoc, serializeDoc } from "./doc-format";
 
-export type { BackmatterConfig, BackmatterDirs, ResolvedConfig } from "./config";
+export type { BackmatterConfig, BackmatterDirs, DevBarHostConfig, ResolvedConfig } from "./config";
 export {
   defineConfig,
   resolveConfig,

package/src/preview.ts

@@ -67,6 +67,19 @@ export type DevMode = {
   tree?: string;
 };
 
+/** Why the host session endpoint refused to open the bar. */
+export type HostSessionReason = "invalid" | "anonymous" | "unavailable";
+
+export type HostPreviewSession = {
+  /** Draft preview is on (checkout cookie + draft mode). */
+  enabled: boolean;
+  /** Signed into the site session but viewing the published site. */
+  signedIn?: boolean;
+  branch?: string;
+  tree?: string;
+  reason?: HostSessionReason;
+};
+
 export function resolveDevMode(session: {
   enabled: boolean;
   branch?: string;
@@ -79,28 +92,36 @@ 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 };
-    return {
-      enabled: true,
-      ...(typeof data.branch === "string" && data.branch ? { branch: data.branch } : {}),
-      ...(typeof data.tree === "string" && data.tree ? { tree: data.tree } : {}),
-    };
+    const branch =
+      typeof data.branch === "string" && data.branch ? { branch: data.branch } : {};
+    const tree = typeof data.tree === "string" && data.tree ? { tree: data.tree } : {};
+    if (data.mode === "preview") {
+      return { enabled: true, signedIn: true, ...branch, ...tree };
+    }
+    if (data.signedIn === true) {
+      return { enabled: false, signedIn: true, ...branch, ...tree };
+    }
+    return { enabled: false, reason: hostSessionReason(data.reason) };
   } catch {
-    return { enabled: false };
+    return { enabled: false, reason: "unavailable" };
   }
 }
 
@@ -117,6 +138,34 @@ export async function clearHostPreviewSession(origin = ""): Promise<boolean> {
   }
 }
 
+/** Turn off draft preview but keep the site login session and bar marker. */
+export async function setHostSiteLive(origin = ""): Promise<boolean> {
+  try {
+    const res = await fetch(`${origin.replace(/\/$/, "")}/api/backmatter/preview?live=1`, {
+      method: "POST",
+      credentials: "same-origin",
+      cache: "no-store",
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** Re-enable draft preview for the current site session checkout. */
+export async function setHostSitePreview(origin = ""): Promise<boolean> {
+  try {
+    const res = await fetch(`${origin.replace(/\/$/, "")}/api/backmatter/preview?preview=1`, {
+      method: "POST",
+      credentials: "same-origin",
+      cache: "no-store",
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
 export type CmsSessionUser = { id: string; email: string; name: string };
 
 /** Cookie session on the CMS API. Fail closed: empty URL, 401, errors → null. */