@backmatter/core 0.0.25 → 0.0.27

package/package.json

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

package/src/config.ts

@@ -7,6 +7,8 @@ import { detectGitBranch } from "./sync-schema";
 export type DevBarHostConfig = {
   /** Draw a viewport ring and top pill while the site session is in preview. */
   previewFrame?: boolean;
+  /** Bottom corner radius (px) for the preview ring (host window lip below the chrome). */
+  previewFrameRadius?: number;
 };
 
 export type BackmatterDirs = {

package/src/index.ts

@@ -10,6 +10,8 @@ export type {
 export { field, serializeField, parseFieldSnapshot } from "./fields";
 export {
   MAX_MEDIA_BYTES,
+  MAX_MEDIA_TEXT,
+  MAX_VARIANT_WIDTH,
   MEDIA_CONTENT_TYPES,
   MEDIA_WIDTHS,
   isMediaContentType,
@@ -92,6 +94,14 @@ export {
   sortByRouteSpecificity,
 } from "./routes";
 
+export type { PageNavDoc, PageNavItem } from "./page-nav";
+export {
+  PAGE_NAV_DEFAULT_LIMIT,
+  PAGE_NAV_MAX_LIMIT,
+  pageNavItems,
+  paginatePageNavItems,
+} from "./page-nav";
+
 export type { PathMatch, ContentSource, ParsedContentKey } from "./path";
 export {
   compilePathPattern,

package/src/media-url.ts

@@ -1,13 +1,19 @@
 // packages/core/src/media-url.ts
 
-/** Widths the catalog lists for the gallery. A public URL may use any positive width. */
+/** Widths the catalog lists for the gallery. */
 export const MEDIA_WIDTHS = [400, 800, 1200, 2000] as const;
 
+/** Widest variant the CDN will resize. A wider request is refused. */
+export const MAX_VARIANT_WIDTH = 2000;
+
 export type MediaWidth = (typeof MEDIA_WIDTHS)[number];
 
 /** Bytes the catalog accepts for one file. */
 export const MAX_MEDIA_BYTES = 20 * 1024 * 1024;
 
+/** Characters of alt text or caption the catalog stores on one image. */
+export const MAX_MEDIA_TEXT = 500;
+
 export const MEDIA_CONTENT_TYPES = [
   "image/jpeg",
   "image/png",
@@ -39,7 +45,9 @@ export function mediaVariantUrl(
   id: string,
   width: number,
 ): string | null {
-  if (!isMediaId(id) || !Number.isInteger(width) || width < 1) return null;
+  if (!isMediaId(id) || !Number.isInteger(width) || width < 1 || width > MAX_VARIANT_WIDTH) {
+    return null;
+  }
   return `${origin.replace(/\/$/, "")}/img/${id}/width=${width},format=auto`;
 }
 

package/src/node/media-cli.ts

@@ -112,7 +112,7 @@ async function media(
     if (flags.width) {
       const width = Number(flags.width);
       const url = mediaVariantUrl(origin, id, width);
-      if (!url) throw new Error("width must be a positive integer");
+      if (!url) throw new Error("width must be a positive integer up to 2000");
       io.log(url);
       return 0;
     }

package/src/page-nav.ts

@@ -0,0 +1,67 @@
+// packages/core/src/page-nav.ts
+import { isRoutable, routeFor, type RouteModel } from "./routes";
+
+export type PageNavDoc = {
+  locale: string;
+  type: string;
+  slug: string;
+};
+
+export type PageNavItem = {
+  key: string;
+  label: string;
+  href: string;
+  current: boolean;
+};
+
+/** Routable documents, in label order. Unroutable models stay out of the menu. */
+export function pageNavItems(input: {
+  docs: readonly PageNavDoc[];
+  models: readonly RouteModel[];
+  current: PageNavDoc | null;
+}): PageNavItem[] {
+  const byType = new Map(input.models.map((model) => [model.type, model]));
+  const locales = new Set(input.docs.map((doc) => doc.locale));
+  const showLocale = locales.size > 1;
+  const items: PageNavItem[] = [];
+  for (const doc of input.docs) {
+    const model = byType.get(doc.type);
+    if (!model || !isRoutable(model)) continue;
+    const href = routeFor(model, doc.locale, doc.slug);
+    if (!href) continue;
+    const name = `${doc.type}/${doc.slug}`;
+    items.push({
+      key: `${doc.locale}/${doc.type}/${doc.slug}`,
+      label: showLocale ? `${name} · ${doc.locale}` : name,
+      href,
+      current: Boolean(
+        input.current &&
+          input.current.locale === doc.locale &&
+          input.current.type === doc.type &&
+          input.current.slug === doc.slug,
+      ),
+    });
+  }
+  items.sort((a, b) => a.label.localeCompare(b.label));
+  return items;
+}
+
+export const PAGE_NAV_DEFAULT_LIMIT = 10;
+export const PAGE_NAV_MAX_LIMIT = 50;
+
+export function paginatePageNavItems(
+  items: readonly PageNavItem[],
+  query: { q?: string; limit?: number; offset?: number },
+): { items: PageNavItem[]; total: number } {
+  const needle = query.q?.trim().toLowerCase() ?? "";
+  const filtered = needle ? items.filter((item) => item.label.toLowerCase().includes(needle)) : [...items];
+  const limit = Math.min(
+    PAGE_NAV_MAX_LIMIT,
+    Math.max(1, query.limit ?? PAGE_NAV_DEFAULT_LIMIT),
+  );
+  const offset = Math.max(0, query.offset ?? 0);
+  return {
+    items: filtered.slice(offset, offset + limit),
+    total: filtered.length,
+  };
+}

package/src/preview-channel.ts

@@ -49,12 +49,38 @@ export type PreviewStatusMessage = Envelope & {
   message?: string;
 };
 
+export function normalizePointerQuote(quote: string): string {
+  return quote.replace(/\s+/g, " ").trim().slice(0, 240);
+}
+
+export type PreviewPointMessage = Envelope & {
+  type: "backmatter:point";
+  on: boolean;
+};
+
+export type PreviewGrabMessage = Envelope & {
+  type: "backmatter:grab";
+  blockId: string;
+  blockType: string | null;
+  blockIndex: number | null;
+  quote: string;
+  shift: boolean;
+};
+
+export type PreviewHighlightMessage = Envelope & {
+  type: "backmatter:highlight";
+  blockId: string | null;
+};
+
 export type PreviewChannelMessage =
   | PreviewHelloMessage
   | PreviewDocMessage
   | PreviewNavigateMessage
   | PreviewRemovedMessage
   | PreviewStatusMessage
+  | PreviewPointMessage
+  | PreviewGrabMessage
+  | PreviewHighlightMessage
   | PreviewHotkeyMessage;
 
 export type PreviewTransport = {
@@ -139,6 +165,36 @@ export function parsePreviewMessage(data: unknown): PreviewChannelMessage | null
         ...(typeof data.message === "string" ? { message: data.message } : {}),
       };
     }
+    case "backmatter:point": {
+      if (typeof data.on !== "boolean") return null;
+      return { type: "backmatter:point", ...envelope, on: data.on };
+    }
+    case "backmatter:grab": {
+      if (typeof data.blockId !== "string" || data.blockId.length === 0) return null;
+      if (data.blockType !== null && typeof data.blockType !== "string") return null;
+      if (
+        data.blockIndex !== null &&
+        (typeof data.blockIndex !== "number" || !Number.isInteger(data.blockIndex) || data.blockIndex < 0)
+      ) {
+        return null;
+      }
+      if (typeof data.quote !== "string" || typeof data.shift !== "boolean") return null;
+      return {
+        type: "backmatter:grab",
+        ...envelope,
+        blockId: data.blockId,
+        blockType: data.blockType,
+        blockIndex: data.blockIndex,
+        quote: normalizePointerQuote(data.quote),
+        shift: data.shift,
+      };
+    }
+    case "backmatter:highlight": {
+      if (data.blockId !== null && (typeof data.blockId !== "string" || data.blockId.length === 0)) {
+        return null;
+      }
+      return { type: "backmatter:highlight", ...envelope, blockId: data.blockId };
+    }
     default:
       return null;
   }

package/src/preview-client.ts

@@ -5,9 +5,11 @@
 // that only a tombstone (`raw: ""`) from SSE still wins.
 
 import {
+  normalizePointerQuote,
   samePreviewRef,
   type PreviewChannelMessage,
   type PreviewChannelRef,
+  type PreviewGrabMessage,
   type PreviewTransport,
 } from "./preview-channel";
 
@@ -35,6 +37,8 @@ export type PreviewPageHandlers = {
   onError?: (message: string) => void;
   onRemoved?: () => void;
   onNavigate?: (path: string) => void;
+  onPoint?: (on: boolean) => void;
+  onHighlight?: (blockId: string | null) => void;
 };
 
 type Job = {
@@ -47,6 +51,8 @@ export type PreviewPageSession = {
   close(): void;
   /** True after the first `doc` for this page's ref. */
   editorAttached(): boolean;
+  grab(grab: Omit<PreviewGrabMessage, "type" | "v" | "ref">): void;
+  point(on: boolean): void;
 };
 
 /**
@@ -154,6 +160,12 @@ export function createPreviewPage(options: {
       case "backmatter:navigate":
         handlers.onNavigate?.(message.path);
         break;
+      case "backmatter:point":
+        handlers.onPoint?.(message.on);
+        break;
+      case "backmatter:highlight":
+        handlers.onHighlight?.(message.blockId);
+        break;
       default:
         break;
     }
@@ -186,6 +198,18 @@ export function createPreviewPage(options: {
 
   return {
     editorAttached: () => attached,
+    grab(grab) {
+      send({
+        type: "backmatter:grab",
+        v: 1,
+        ref: options.ref,
+        ...grab,
+        quote: normalizePointerQuote(grab.quote),
+      });
+    },
+    point(on) {
+      send({ type: "backmatter:point", v: 1, ref: options.ref, on });
+    },
     close() {
       if (closed) return;
       closed = true;
@@ -215,6 +239,8 @@ export type PreviewEditorSession = {
   setDoc(doc: PreviewRenderDoc): void;
   navigate(path: string): void;
   removed(): void;
+  point(on: boolean): void;
+  highlight(blockId: string | null): void;
   close(): void;
 };
 
@@ -225,7 +251,9 @@ export type PreviewEditorSession = {
 export function createPreviewEditor(options: {
   transport: PreviewTransport;
   ref: PreviewChannelRef | (() => PreviewChannelRef);
-  onHello?: (ref: PreviewChannelRef) => void;
+  onHello?: (ref: PreviewChannelRef, capabilities?: string[]) => void;
+  onGrab?: (grab: PreviewGrabMessage) => void;
+  onPoint?: (on: boolean) => void;
   onStatus?: (status: { seq: number; state: "rendered" | "error"; message?: string }) => void;
   schedule?: PreviewSchedule;
 }): PreviewEditorSession {
@@ -254,14 +282,21 @@ export function createPreviewEditor(options: {
 
   const unsubscribe = options.transport.subscribe((message) => {
     if (closed) return;
-    if (message.type === "backmatter:hello") options.onHello?.(message.ref);
-    if (message.type === "backmatter:status" && samePreviewRef(message.ref, currentRef())) {
+    if (message.type === "backmatter:hello") {
+      options.onHello?.(message.ref, message.capabilities);
+      return;
+    }
+    if (message.type === "backmatter:hotkey") return;
+    if (!samePreviewRef(message.ref, currentRef())) return;
+    if (message.type === "backmatter:status") {
       options.onStatus?.({
         seq: message.seq,
         state: message.state,
         ...(message.message ? { message: message.message } : {}),
       });
     }
+    if (message.type === "backmatter:grab") options.onGrab?.(message);
+    if (message.type === "backmatter:point") options.onPoint?.(message.on);
   });
 
   return {
@@ -279,6 +314,14 @@ export function createPreviewEditor(options: {
       if (closed) return;
       options.transport.send({ type: "backmatter:removed", v: 1, ref: currentRef() });
     },
+    point(on) {
+      if (closed) return;
+      options.transport.send({ type: "backmatter:point", v: 1, ref: currentRef(), on });
+    },
+    highlight(blockId) {
+      if (closed) return;
+      options.transport.send({ type: "backmatter:highlight", v: 1, ref: currentRef(), blockId });
+    },
     close() {
       if (closed) return;
       closed = true;

package/src/preview-pointer.ts

@@ -0,0 +1,63 @@
+// packages/core/src/preview-pointer.ts
+
+export type PointerArmSource = "editor" | "devbar";
+
+export type PointerHit = {
+  blockId: string | null;
+  blockType: string | null;
+  blockIndex: number | null;
+  quote: string;
+  shift: boolean;
+};
+
+export type RoutedGrab = {
+  blockId: string;
+  blockType: string | null;
+  blockIndex: number | null;
+  quote: string;
+  shift: boolean;
+};
+
+export type PointerRoute =
+  | { to: "editor"; grab: RoutedGrab }
+  | { to: "devbar"; grab: Omit<PointerHit, "shift"> }
+  | { to: "none" };
+
+export function routePointerHit(source: PointerArmSource | null, hit: PointerHit): PointerRoute {
+  if (hit.shift && hit.blockId) {
+    return {
+      to: "editor",
+      grab: {
+        blockId: hit.blockId,
+        blockType: hit.blockType,
+        blockIndex: hit.blockIndex,
+        quote: hit.quote,
+        shift: true,
+      },
+    };
+  }
+  if (source === "devbar") {
+    return {
+      to: "devbar",
+      grab: {
+        blockId: hit.blockId,
+        blockType: hit.blockType,
+        blockIndex: hit.blockIndex,
+        quote: hit.quote,
+      },
+    };
+  }
+  if (source === "editor" && hit.blockId) {
+    return {
+      to: "editor",
+      grab: {
+        blockId: hit.blockId,
+        blockType: hit.blockType,
+        blockIndex: hit.blockIndex,
+        quote: hit.quote,
+        shift: false,
+      },
+    };
+  }
+  return { to: "none" };
+}

package/src/preview.ts

@@ -304,6 +304,7 @@ export {
   createWindowPreviewTransport,
   isAllowedPreviewOrigin,
   normalizePreviewOrigin,
+  normalizePointerQuote,
   parsePreviewMessage,
   PREVIEW_CHANNEL_VERSION,
   samePreviewRef,
@@ -313,14 +314,26 @@ export type {
   PreviewChannelMessage,
   PreviewChannelRef,
   PreviewDocMessage,
+  PreviewGrabMessage,
   PreviewHelloMessage,
+  PreviewHighlightMessage,
   PreviewMessageEvent,
   PreviewNavigateMessage,
+  PreviewPointMessage,
   PreviewRemovedMessage,
   PreviewStatusMessage,
   PreviewTransport,
   PreviewWindowLike,
 } from "./preview-channel";
+export {
+  routePointerHit,
+} from "./preview-pointer";
+export type {
+  PointerArmSource,
+  PointerHit,
+  PointerRoute,
+  RoutedGrab,
+} from "./preview-pointer";
 export { createPreviewEditor, createPreviewPage } from "./preview-client";
 export type {
   PreviewEditorSession,