@backmatter/core 0.0.26 → 0.0.27

package/package.json

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

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,