@backmatter/studio 0.0.1

package/src/pages/body-blocks.ts

@@ -0,0 +1,233 @@
+// packages/studio/src/pages/body-blocks.ts
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkMdx from "remark-mdx";
+
+export type BodyBlockKind = "text" | "code" | "jsx";
+
+export type BodyBlock = {
+  id: string;
+  markdown: string;
+  kind: BodyBlockKind;
+  lang?: string;
+  jsxName?: string;
+};
+
+type ParsedNode = {
+  type: string;
+  name?: string | null;
+  lang?: string | null;
+  position?: {
+    start: { offset?: number };
+    end: { offset?: number };
+  };
+};
+
+const parseBody = unified().use(remarkParse).use(remarkGfm).use(remarkMdx);
+
+export function blocksFromSource(
+  source: string,
+  idFor: () => string = () => crypto.randomUUID(),
+): BodyBlock[] {
+  if (!source.trim()) return [];
+  const tree = parseBody.parse(source);
+  return (tree.children as ParsedNode[]).flatMap((node) => {
+    const block = blockFromNode(source, node, idFor());
+    return block ? [block] : [];
+  });
+}
+
+export function blockFromMarkdown(markdown: string, id: string): BodyBlock {
+  if (!markdown.trim()) return { id, markdown: "", kind: "text" };
+  return blocksFromSource(markdown, () => id)[0] ?? { id, markdown, kind: "text" };
+}
+
+export function joinBlocks(blocks: { markdown: string }[]): string {
+  return blocks.map((block) => block.markdown.replace(/^\n+|\n+$/g, "")).join("\n\n");
+}
+
+export function codeParts(markdown: string): { lang: string; code: string } {
+  const match = /^```([^\n]*)\n?([\s\S]*?)\n?```$/.exec(markdown.trim());
+  if (!match) return { lang: "", code: markdown };
+  return { lang: match[1]?.trim() ?? "", code: match[2] ?? "" };
+}
+
+export function replaceJsxChildren(source: string, name: string, text: string): string {
+  const match = new RegExp(`^(\\s*<${name}\\b[^>]*>)([\\s\\S]*)(</${name}>\\s*)$`).exec(
+    source.trim(),
+  );
+  if (!match) return source;
+  const body = text.trim();
+  if (!body) return `${match[1]}${match[3]}`;
+  return `${match[1]}\n\n${body}\n\n${match[3]}`;
+}
+
+type JsxAttributeValue = {
+  type?: string;
+  value?: string;
+  data?: {
+    estree?: {
+      body?: Array<{ expression?: { type?: string; value?: unknown } }>;
+    };
+  };
+};
+
+type JsxAttribute = {
+  type: string;
+  name?: string;
+  value?: string | null | JsxAttributeValue;
+};
+
+type JsxElement = ParsedNode & {
+  attributes?: JsxAttribute[];
+  children?: ParsedNode[];
+};
+
+export function propsFromJsx(markdown: string): Record<string, unknown> {
+  const node = jsxElement(markdown);
+  if (!node?.attributes) return {};
+  const props: Record<string, unknown> = {};
+  for (const attr of node.attributes) {
+    if (attr.type !== "mdxJsxAttribute" || typeof attr.name !== "string") continue;
+    props[attr.name] = attributeValue(attr.value);
+  }
+  return props;
+}
+
+export function jsxBlockSource(
+  name: string,
+  props: Record<string, unknown>,
+  fields: Record<string, { kind: string }>,
+): string {
+  return elementSource(name, attrList(props, fields));
+}
+
+export function jsxWithProps(
+  markdown: string,
+  name: string,
+  props: Record<string, unknown>,
+  fields: Record<string, { kind: string }>,
+): string {
+  const previous = propsFromJsx(markdown);
+  const merged: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(previous)) {
+    if (!(key in fields)) merged[key] = value;
+  }
+  for (const key of Object.keys(fields)) merged[key] = props[key];
+  const kinds: Record<string, { kind: string }> = { ...fields };
+  for (const key of Object.keys(merged)) {
+    if (!kinds[key]) kinds[key] = { kind: kindOf(merged[key]) };
+  }
+  const tag = elementSource(name, attrList(merged, kinds));
+  const inner = jsxInner(markdown);
+  if (inner == null) return tag;
+  const open = tag.replace(/\s*\/>$/, ">");
+  const body = inner.trim();
+  if (!body) return `${open}</${name}>`;
+  return `${open}\n\n${body}\n\n</${name}>`;
+}
+
+function jsxElement(markdown: string): JsxElement | null {
+  const tree = parseBody.parse(markdown);
+  const node = (tree.children as JsxElement[]).find((child) => child.type === "mdxJsxFlowElement");
+  return node ?? null;
+}
+
+function jsxInner(markdown: string): string | null {
+  const node = jsxElement(markdown);
+  const children = node?.children ?? [];
+  if (children.length === 0) return null;
+  const start = children[0]?.position?.start.offset;
+  const end = children[children.length - 1]?.position?.end.offset;
+  if (typeof start !== "number" || typeof end !== "number") return null;
+  return markdown.slice(start, end);
+}
+
+function attrList(
+  props: Record<string, unknown>,
+  fields: Record<string, { kind: string }>,
+): string[] {
+  const attrs: string[] = [];
+  for (const [key, value] of Object.entries(props)) {
+    const attr = attrSource(key, value, fields[key]?.kind ?? kindOf(value));
+    if (attr) attrs.push(attr);
+  }
+  return attrs;
+}
+
+function elementSource(name: string, attrs: string[]): string {
+  if (attrs.length === 0) return `<${name} />`;
+  if (attrs.join(" ").length < 48) return `<${name} ${attrs.join(" ")} />`;
+  return `<${name}\n${attrs.map((attr) => `  ${attr}`).join("\n")}\n/>`;
+}
+
+function attrSource(name: string, value: unknown, kind: string): string | null {
+  if (value == null || value === "") return null;
+  if (kind === "boolean") return value === true ? name : null;
+  if (kind === "number") {
+    const numeric = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(numeric)) return null;
+    return `${name}={${numeric}}`;
+  }
+  if (kind === "object" || kind === "array") {
+    const json = typeof value === "string" ? value : JSON.stringify(value);
+    try {
+      JSON.parse(json);
+    } catch {
+      return null;
+    }
+    return `${name}={${json}}`;
+  }
+  return `${name}=${JSON.stringify(String(value))}`;
+}
+
+function attributeValue(value: JsxAttribute["value"]): unknown {
+  if (value == null) return true;
+  if (typeof value === "string") return value;
+  const literal = value.data?.estree?.body?.[0]?.expression;
+  if (literal?.type === "Literal" && "value" in literal) return literal.value;
+  const raw = value.value?.trim() ?? "";
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+  if (
+    (raw.startsWith("{") && raw.endsWith("}")) ||
+    (raw.startsWith("[") && raw.endsWith("]"))
+  ) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  if (
+    (raw.startsWith('"') && raw.endsWith('"')) ||
+    (raw.startsWith("'") && raw.endsWith("'"))
+  ) {
+    return raw.slice(1, -1);
+  }
+  return raw;
+}
+
+function kindOf(value: unknown): string {
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return "number";
+  if (Array.isArray(value)) return "array";
+  if (value && typeof value === "object") return "object";
+  return "text";
+}
+
+function blockFromNode(source: string, node: ParsedNode, id: string): BodyBlock | null {
+  const start = node.position?.start.offset;
+  const end = node.position?.end.offset;
+  if (typeof start !== "number" || typeof end !== "number") return null;
+  const markdown = source.slice(start, end);
+  if (node.type === "code") {
+    return { id, markdown, kind: "code", lang: node.lang ?? "" };
+  }
+  if (node.type === "mdxJsxFlowElement") {
+    return { id, markdown, kind: "jsx", jsxName: node.name ?? "" };
+  }
+  return { id, markdown, kind: "text" };
+}

package/src/pages/body-mdx.tsx

@@ -0,0 +1,82 @@
+// packages/studio/src/pages/body-mdx.tsx
+import {
+  Caption,
+  Frame,
+  Image,
+  Link,
+  createMdxComponents,
+  type ProseUIImageProps,
+  type ProseUILinkProps,
+} from "@prose-ui/react";
+import type { AnchorHTMLAttributes, ReactNode } from "react";
+
+function hasCaption(children: ReactNode) {
+  if (children == null || children === false) return false;
+  if (Array.isArray(children) && children.length === 0) return false;
+  return true;
+}
+
+/** Image children are the caption. Prose UI's Image renders the picture only. */
+function BodyImage({
+  children,
+  ...props
+}: ProseUIImageProps & { children?: ReactNode }) {
+  if (!hasCaption(children)) return <Image {...props} />;
+  return (
+    <Frame>
+      <Image {...props} />
+      <Caption>{children}</Caption>
+    </Frame>
+  );
+}
+
+function BodyLink({ children, ...props }: ProseUILinkProps) {
+  return (
+    <Link {...props} target="_blank" rel="noreferrer">
+      {children}
+    </Link>
+  );
+}
+
+function BodyAnchor({
+  children,
+  ...props
+}: AnchorHTMLAttributes<HTMLAnchorElement>) {
+  return (
+    <a {...props} target="_blank" rel="noreferrer">
+      {children}
+    </a>
+  );
+}
+
+export const bodyMdxComponents = {
+  ...createMdxComponents({
+    Image: BodyImage,
+    Link: BodyLink,
+  }),
+  a: BodyAnchor,
+};
+
+/** Shown for `<Quote />` and other tags the editor does not ship a component for. */
+function RichtextTag({
+  children,
+  ...props
+}: { children?: ReactNode } & Record<string, unknown>) {
+  const lines = Object.values(props).filter(
+    (value): value is string => typeof value === "string" && value.trim() !== "",
+  );
+  return (
+    <div>
+      {lines.map((line) => (
+        <p key={line}>{line}</p>
+      ))}
+      {children}
+    </div>
+  );
+}
+
+/** Prose UI keeps `Image`. Other richtext tags get a stand-in so MDX does not throw. */
+export function editorMdxComponents(jsxName?: string): Record<string, unknown> {
+  if (!jsxName || jsxName in bodyMdxComponents) return bodyMdxComponents;
+  return { ...bodyMdxComponents, [jsxName]: RichtextTag };
+}

package/src/pages/compile-body.ts

@@ -0,0 +1,37 @@
+// packages/studio/src/pages/compile-body.ts
+import { evaluate } from "@mdx-js/mdx";
+import { createElement, type ReactNode } from "react";
+import * as runtime from "react/jsx-runtime";
+
+let pluginsPromise: ReturnType<typeof loadPlugins> | null = null;
+
+function loadPlugins() {
+  return import("@prose-ui/core").then(({ remarkPlugins }) => remarkPlugins());
+}
+
+export async function compileBody(
+  source: string,
+  components: object,
+): Promise<{ node: ReactNode; error: string | null }> {
+  if (!source.trim()) return { node: null, error: null };
+
+  try {
+    pluginsPromise ??= loadPlugins().catch((err) => {
+      pluginsPromise = null;
+      throw err;
+    });
+    const remarkPlugins = await pluginsPromise;
+    const { default: Content } = await evaluate(source, {
+      ...runtime,
+      remarkPlugins,
+      baseUrl: import.meta.url,
+    });
+    return {
+      node: createElement(Content, { components: components as never }),
+      error: null,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Could not render this body";
+    return { node: null, error: message };
+  }
+}

package/src/pages/host-env.ts

@@ -0,0 +1,22 @@
+// packages/studio/src/pages/host-env.ts
+/** Copy-paste block for the Next host's Vercel env / `.env`. */
+
+export function hostEnvSnippet(input: {
+  workspaceId: string;
+  contentToken?: string | null;
+  previewToken?: string | null;
+  hostToken?: string | null;
+  siteUrl?: string | null;
+}): string {
+  const line = (name: string, value: string | null | undefined) =>
+    `${name}=${value?.trim() ?? ""}`;
+  return [
+    `# backmatter.config.ts → workspaceId: "${input.workspaceId}"`,
+    "# API defaults to https://api.backmatter.app in production",
+    "# BACKMATTER_API_URL=http://localhost:3001  # local or self-hosted CMS",
+    line("BACKMATTER_PREVIEW_TOKEN", input.previewToken),
+    line("BACKMATTER_HOST_TOKEN", input.hostToken),
+    line("BACKMATTER_CONTENT_TOKEN", input.contentToken),
+    line("BACKMATTER_SITE_URL", input.siteUrl),
+  ].join("\n");
+}

package/src/pages/html-to-markdown.ts

@@ -0,0 +1,99 @@
+// packages/studio/src/pages/html-to-markdown.ts
+import { codeParts, replaceJsxChildren, type BodyBlock } from "./body-blocks";
+
+export function markdownFromEditable(root: HTMLElement, block: BodyBlock): string {
+  if (block.kind === "code") {
+    const code = textOf(root.querySelector("code") ?? root).replace(/\n$/, "");
+    const lang = block.lang ?? codeParts(block.markdown).lang;
+    return "```" + lang + "\n" + code + "\n```";
+  }
+  if (block.kind === "jsx" && block.jsxName) {
+    return replaceJsxChildren(block.markdown, block.jsxName, jsxText(root, block.jsxName));
+  }
+  return blockElementsToMarkdown(root).trim();
+}
+
+function textOf(element: Element | null): string {
+  return element instanceof HTMLElement ? element.innerText : "";
+}
+
+function jsxText(root: HTMLElement, name: string): string {
+  if (name === "Image") return textOf(root.querySelector("figcaption"));
+  if (name === "Callout") return textOf(root.querySelector(".callout-body")) || root.innerText;
+  return root.innerText;
+}
+
+function blockElementsToMarkdown(root: HTMLElement): string {
+  const parts: string[] = [];
+  for (const node of root.childNodes) {
+    if (node.nodeType === Node.TEXT_NODE) {
+      const text = inline(node).trim();
+      if (text) parts.push(text);
+      continue;
+    }
+    if (node instanceof HTMLElement) {
+      const markdown = elementToMarkdown(node);
+      if (markdown) parts.push(markdown);
+    }
+  }
+  return parts.join("\n\n");
+}
+
+function elementToMarkdown(element: HTMLElement): string {
+  const tag = element.tagName;
+  if (/^H[1-6]$/.test(tag)) {
+    const level = Number(tag.slice(1));
+    return `${"#".repeat(level)} ${inline(element).trim()}`;
+  }
+  if (tag === "UL") return list(element, "ul");
+  if (tag === "OL") return list(element, "ol");
+  if (tag === "BLOCKQUOTE") {
+    const inner = blockElementsToMarkdown(element);
+    return inner
+      .split("\n")
+      .map((line) => (line.length > 0 ? `> ${line}` : ">"))
+      .join("\n");
+  }
+  if (tag === "P" || tag === "DIV") return inline(element).trim();
+  return inline(element).trim();
+}
+
+function list(element: HTMLElement, kind: "ul" | "ol"): string {
+  const items = [...element.children].filter((child) => child.tagName === "LI");
+  return items
+    .map((item, index) => {
+      const marker = kind === "ul" ? "-" : `${index + 1}.`;
+      return `${marker} ${inline(item).trim()}`;
+    })
+    .join("\n");
+}
+
+function inline(node: Node): string {
+  if (node.nodeType === Node.TEXT_NODE) {
+    return (node.textContent ?? "").replace(/\u00a0/g, " ");
+  }
+  if (!(node instanceof HTMLElement)) return "";
+  const tag = node.tagName;
+  if (tag === "STRONG" || tag === "B") return wrap(node, "**");
+  if (tag === "EM" || tag === "I") return wrap(node, "*");
+  if (tag === "CODE") {
+    const text = node.textContent ?? "";
+    return text ? `\`${text}\`` : "";
+  }
+  if (tag === "A") {
+    const href = node.getAttribute("href") ?? "";
+    const text = children(node);
+    return text ? `[${text}](${href})` : "";
+  }
+  if (tag === "BR") return "\n";
+  return children(node);
+}
+
+function wrap(element: HTMLElement, marker: string): string {
+  const text = children(element);
+  return text ? `${marker}${text}${marker}` : "";
+}
+
+function children(element: HTMLElement): string {
+  return [...element.childNodes].map(inline).join("");
+}

package/src/pages/preview-bridge.ts

@@ -0,0 +1,46 @@
+// packages/studio/src/pages/preview-bridge.ts
+// Dashboard side of the preview channel: push the open document into the
+// iframe, and surface "Edit this page" when the iframe navigates elsewhere.
+import {
+  createPreviewEditor,
+  createWindowPreviewTransport,
+  samePreviewRef,
+  type PreviewChannelRef,
+  type PreviewEditorSession,
+  type PreviewSchedule,
+  type PreviewTransport,
+  type PreviewWindowLike,
+} from "@backmatter/core/preview";
+
+export function bindPreviewEditor(options: {
+  transport: PreviewTransport;
+  ref: () => PreviewChannelRef;
+  onOffer: (ref: PreviewChannelRef | null) => void;
+  onStatus: (state: "rendered" | "error") => void;
+  schedule?: PreviewSchedule;
+}): PreviewEditorSession {
+  return createPreviewEditor({
+    transport: options.transport,
+    ref: options.ref,
+    schedule: options.schedule,
+    onHello: (hello) => {
+      options.onOffer(samePreviewRef(options.ref(), hello) ? null : hello);
+    },
+    onStatus: (status) => options.onStatus(status.state),
+  });
+}
+
+export function previewFrameTransport(options: {
+  frame: HTMLIFrameElement;
+  siteOrigin: string;
+  host?: PreviewWindowLike;
+}): PreviewTransport | null {
+  const target = options.frame.contentWindow;
+  if (!target) return null;
+  return createWindowPreviewTransport({
+    target,
+    targetOrigin: options.siteOrigin,
+    allowedOrigins: [options.siteOrigin],
+    host: options.host,
+  });
+}

package/src/pages/preview-split.ts

@@ -0,0 +1,30 @@
+// packages/studio/src/pages/preview-split.ts
+export const PREVIEW_PCT_KEY = "backmatter-editor-preview-pct";
+export const PREVIEW_PCT_DEFAULT = 46;
+export const PREVIEW_PCT_MIN = 22;
+export const PREVIEW_PCT_MAX = 78;
+export const WIDE_QUERY = "(min-width: 1024px)";
+
+export function clampPreviewPct(value: number) {
+  return Math.min(PREVIEW_PCT_MAX, Math.max(PREVIEW_PCT_MIN, value));
+}
+
+export function readPreviewPct() {
+  try {
+    const raw = localStorage.getItem(PREVIEW_PCT_KEY);
+    const value = raw == null ? NaN : Number(raw);
+    if (Number.isFinite(value)) return clampPreviewPct(value);
+  } catch {
+    // ignore quota / private mode
+  }
+  return PREVIEW_PCT_DEFAULT;
+}
+
+export function persistPreviewPct(value: number) {
+  if (!Number.isFinite(value)) return;
+  try {
+    localStorage.setItem(PREVIEW_PCT_KEY, String(clampPreviewPct(value)));
+  } catch {
+    // ignore quota / private mode
+  }
+}

package/src/pages/preview-url.ts

@@ -0,0 +1,92 @@
+// packages/studio/src/pages/preview-url.ts
+import { routeFor, revalidateUrl, type RouteModel } from "@backmatter/core";
+
+export function modelForType(models: readonly RouteModel[], type: string): RouteModel {
+  return models.find((m) => m.type === type) ?? { type };
+}
+
+export function publicDocPath(model: RouteModel, locale: string, slug: string): string {
+  return routeFor(model, locale, slug);
+}
+
+/** Public path once checkout is known. Null holds the iframe off HEAD. */
+export function editorPreviewPath(
+  model: RouteModel,
+  slug: string,
+  locale = "en",
+  branch?: string | null,
+  tree?: string | null,
+): string | null {
+  if (!branch?.trim() || !tree?.trim()) return null;
+  return publicDocPath(model, locale, slug);
+}
+
+/**
+ * A Studio mounted on the site it previews already carries the site session
+ * cookie, so the preview frame loads the page directly — no ticket.
+ */
+export function studioIsOnSite(siteUrl: string | null | undefined, pageOrigin: string): boolean {
+  if (!siteUrl) return false;
+  try {
+    return new URL(siteUrl).origin === pageOrigin;
+  } catch {
+    return false;
+  }
+}
+
+export function onSitePreviewUrl(siteUrl: string, path: string): string {
+  return `${siteUrl.replace(/\/$/, "")}${path}`;
+}
+
+export function previewEnableUrl(base: string, ticket: string): string {
+  const origin = base.replace(/\/$/, "");
+  return `${origin}/api/backmatter/preview?ticket=${encodeURIComponent(ticket)}`;
+}
+
+export function primarySiteUrl(
+  siteUrls: readonly string[] | null | undefined,
+): string | null {
+  const first = siteUrls?.[0]?.trim();
+  return first ? first : null;
+}
+
+/** Live published page. No preview ticket. */
+export function productionDocUrl(
+  siteUrl: string | null | undefined,
+  model: RouteModel,
+  locale: string,
+  slug: string,
+): string | null {
+  const origin = siteUrl?.trim().replace(/\/$/, "");
+  if (!origin) return null;
+  return `${origin}${publicDocPath(model, locale, slug)}`;
+}
+
+export function revalidateWebhookUrl(siteUrl: string | null | undefined): string | null {
+  const origin = siteUrl?.trim();
+  if (!origin) return null;
+  return revalidateUrl(origin);
+}
+
+export function previewSiteUrl(
+  siteUrls: readonly string[] | null | undefined,
+  ticket: string | null,
+): string | null {
+  if (!ticket) return null;
+  const base = primarySiteUrl(siteUrls);
+  if (!base) return null;
+  return previewEnableUrl(base, ticket);
+}
+
+export function buildPreviewSiteUrl(
+  base: string,
+  model: RouteModel,
+  slug: string,
+  locale = "en",
+  branch?: string | null,
+  tree?: string | null,
+  ticket?: string | null,
+): string | null {
+  if (!editorPreviewPath(model, slug, locale, branch, tree) || !ticket) return null;
+  return previewEnableUrl(base, ticket);
+}