Merge pull request #60 from jphastings/refined-by

scanash00 · web-flow · commit ea55c0cff02e · 2026-06-28T19:55:44.000-08:00
Adding support for refinedBy and physical book page numbers
diff --git a/Dockerfile b/Dockerfile
@@ -4,6 +4,8 @@ WORKDIR /app/web
 COPY web/package.json web/bun.lock ./
 RUN bun install
 COPY web/ ./
+# Lexicons are the source of truth for schema docs rendered by the web build.
+COPY lexicons/ /app/lexicons/
 RUN bun run build
 
 FROM golang:1.25-alpine AS backend-builder
diff --git a/backend/internal/api/hydration.go b/backend/internal/api/hydration.go
@@ -36,14 +36,15 @@ type Author struct {
 }
 
 type APISelector struct {
-	Type       string `json:"type"`
-	Exact      string `json:"exact,omitempty"`
-	Prefix     string `json:"prefix,omitempty"`
-	Suffix     string `json:"suffix,omitempty"`
-	Start      *int   `json:"start,omitempty"`
-	End        *int   `json:"end,omitempty"`
-	Value      string `json:"value,omitempty"`
-	ConformsTo string `json:"conformsTo,omitempty"`
+	Type       string       `json:"type"`
+	Exact      string       `json:"exact,omitempty"`
+	Prefix     string       `json:"prefix,omitempty"`
+	Suffix     string       `json:"suffix,omitempty"`
+	Start      *int         `json:"start,omitempty"`
+	End        *int         `json:"end,omitempty"`
+	Value      string       `json:"value,omitempty"`
+	ConformsTo string       `json:"conformsTo,omitempty"`
+	RefinedBy  *APISelector `json:"refinedBy,omitempty"`
 }
 
 type APIBody struct {
diff --git a/backend/internal/service/hydration.go b/backend/internal/service/hydration.go
@@ -11,14 +11,15 @@ import (
 )
 
 type APISelector struct {
-	Type       string `json:"type"`
-	Exact      string `json:"exact,omitempty"`
-	Prefix     string `json:"prefix,omitempty"`
-	Suffix     string `json:"suffix,omitempty"`
-	Start      *int   `json:"start,omitempty"`
-	End        *int   `json:"end,omitempty"`
-	Value      string `json:"value,omitempty"`
-	ConformsTo string `json:"conformsTo,omitempty"`
+	Type       string       `json:"type"`
+	Exact      string       `json:"exact,omitempty"`
+	Prefix     string       `json:"prefix,omitempty"`
+	Suffix     string       `json:"suffix,omitempty"`
+	Start      *int         `json:"start,omitempty"`
+	End        *int         `json:"end,omitempty"`
+	Value      string       `json:"value,omitempty"`
+	ConformsTo string       `json:"conformsTo,omitempty"`
+	RefinedBy  *APISelector `json:"refinedBy,omitempty"`
 }
 
 type APIBody struct {
diff --git a/lexicons/at/margin/note.json b/lexicons/at/margin/note.json
@@ -1,7 +1,7 @@
 {
   "lexicon": 1,
   "id": "at.margin.note",
-  "revision": 3,
+  "revision": 4,
   "description": "W3C Web Annotation Data Model compliant unified note record for ATProto",
   "defs": {
     "main": {
@@ -171,8 +171,7 @@
             "TextPositionSelector",
             "CssSelector",
             "XPathSelector",
-            "FragmentSelector",
-            "RangeSelector"
+            "FragmentSelector"
           ]
         },
         "exact": {
@@ -212,6 +211,11 @@
           "type": "string",
           "format": "uri",
           "description": "FragmentSelector: URI of the specification the fragment conforms to"
+        },
+        "refinedBy": {
+          "type": "ref",
+          "ref": "#selector",
+          "description": "W3C refinement: a further selector applied within the region this selector identifies (e.g. a FragmentSelector locating a page or CFI range inside a TextQuoteSelector match)."
         }
       }
     },
diff --git a/web/astro.config.mjs b/web/astro.config.mjs
@@ -11,6 +11,42 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const API_PORT = process.env.API_PORT || 8081;
 
+function lexiconsPlugin() {
+  const virtualId = "virtual:lexicons";
+  const resolvedId = "\0" + virtualId;
+  return {
+    name: "lexicons",
+    /** @param {string} id */
+    resolveId(id) {
+      if (id === virtualId) return resolvedId;
+    },
+    /** @param {string} id */
+    load(id) {
+      if (id !== resolvedId) return;
+      // Single source of truth: every lexicon in ../lexicons, keyed by its NSID
+      // id, read raw at build time so docs never drift from the schema.
+      const lexiconsDir = join(__dirname, "../lexicons");
+      /** @type {Record<string, string>} */
+      const lexicons = {};
+      /** @param {string} dir */
+      const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          const full = join(dir, entry.name);
+          if (entry.isDirectory()) {
+            walk(full);
+          } else if (entry.name.endsWith(".json")) {
+            const text = readFileSync(full, "utf-8").trimEnd();
+            const id = JSON.parse(text).id;
+            if (id) lexicons[id] = text;
+          }
+        }
+      };
+      walk(lexiconsDir);
+      return `export const lexicons = ${JSON.stringify(lexicons)};`;
+    },
+  };
+}
+
 function i18nResourcesPlugin() {
   const virtualId = "virtual:i18n-resources";
   const resolvedId = "\0" + virtualId;
@@ -89,7 +125,7 @@ export default defineConfig({
     defaultStrategy: "viewport",
   },
   vite: {
-    plugins: [i18nResourcesPlugin(), i18nLanguagesPlugin()],
+    plugins: [lexiconsPlugin(), i18nResourcesPlugin(), i18nLanguagesPlugin()],
     resolve: {
       alias: {
         "@": resolve(__dirname, "src"),
diff --git a/web/src/api/client.ts b/web/src/api/client.ts
@@ -7,6 +7,7 @@ import type {
   NotificationItem,
   Selector,
   Target,
+  TextQuoteSelector,
   UserProfile,
 } from "../types";
 
@@ -341,7 +342,7 @@ interface CreateAnnotationParams {
   url: string;
   text?: string;
   title?: string;
-  selector?: { exact: string; prefix?: string; suffix?: string };
+  selector?: TextQuoteSelector;
   tags?: string[];
   labels?: string[];
 }
@@ -370,7 +371,7 @@ export async function createAnnotation({
 
 interface CreateHighlightParams {
   url: string;
-  selector: { exact: string; prefix?: string; suffix?: string };
+  selector: TextQuoteSelector;
   color?: string;
   tags?: string[];
   title?: string;
@@ -517,7 +518,7 @@ export async function convertHighlightToAnnotation(
   highlightUri: string,
   url: string,
   text: string,
-  selector?: { exact: string; prefix?: string; suffix?: string },
+  selector?: TextQuoteSelector,
   title?: string,
 ): Promise<{ success: boolean; item?: AnnotationItem; error?: string }> {
   try {
diff --git a/web/src/components/common/Card.tsx b/web/src/components/common/Card.tsx
@@ -46,7 +46,9 @@ import type {
   AnnotationItem,
   ContentLabel,
   LabelVisibility,
+  Selector,
 } from "../../types";
+import { asTextQuote } from "../../types";
 
 import { Avatar } from "../ui";
 import CollectionIcon from "./CollectionIcon";
@@ -105,6 +107,45 @@ function getContentWarning(
   return null;
 }
 
+const PHYSICAL_BOOKS_SPEC = "https://margin.at/docs/specs/physical-books";
+
+// Decode one application/x-www-form-urlencoded component. "+" maps to a space;
+// the replace runs before decodeURIComponent so an escaped plus (%2B) survives.
+const formDecode = (component: string): string =>
+  decodeURIComponent(component.replace(/\+/g, " "));
+
+// Printed page label from a selector's physical-books FragmentSelector, e.g.
+// "255-256", or "A-1 - A-2" when a label itself contains an (encoded) hyphen.
+function bookPageLabel(selector?: Selector | null): string | null {
+  for (
+    let sel: Selector | null | undefined = selector;
+    sel;
+    sel = sel.refinedBy
+  ) {
+    if (
+      sel.type !== "FragmentSelector" ||
+      sel.conformsTo !== PHYSICAL_BOOKS_SPEC ||
+      !sel.value
+    ) {
+      continue;
+    }
+    // Keep the value raw (%2D still encoded) so the range hyphen stays unambiguous.
+    const raw = sel.value
+      .split("&")
+      .map((pair) => pair.split("="))
+      .find(([key]) => key === "page")?.[1];
+    if (!raw) return null;
+    try {
+      const pages = raw.split("-").map(formDecode);
+      const separator = /%2d/i.test(raw) ? " - " : "-";
+      return pages.join(separator);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
 interface CardProps {
   item: AnnotationItem;
   onDelete?: (uri: string) => void;
@@ -252,7 +293,7 @@ export default function Card({
       item.uri,
       pageUrl,
       convertText.trim(),
-      item.target?.selector,
+      asTextQuote(item.target?.selector),
       item.target?.title,
     );
     setConverting(false);
@@ -344,9 +385,10 @@ export default function Card({
   const bookUrl = isbn ? `https://openlibrary.org/isbn/${isbn}` : null;
   const bookTitle =
     item.target?.title || item.title || (isbn ? `ISBN ${isbn}` : null);
+  const bookPage = bookPageLabel(item.target?.selector);
 
   const quoteLinkUrl = (() => {
-    const sel = item.target?.selector;
+    const sel = asTextQuote(item.target?.selector);
     if (!sel?.exact) return null;
     if (bookUrl) return bookUrl;
     if (!pageUrl) return null;
@@ -565,20 +607,29 @@ export default function Card({
           </div>
 
           {pageUrl && !isBookmark && !(contentWarning && !contentRevealed) && (
-            <a
-              href={bookUrl || pageUrl}
-              target="_blank"
-              rel="noopener noreferrer"
-              onClick={(e) => handleExternalClick(e, bookUrl || pageUrl)}
-              className="inline-flex items-center gap-1 text-xs text-primary-600 dark:text-primary-400 hover:underline mt-0.5 max-w-full"
-            >
-              {isbn ? (
-                <BookOpen size={10} className="flex-shrink-0" />
-              ) : (
-                <ExternalLink size={10} className="flex-shrink-0" />
+            <div className="flex items-center gap-1.5 mt-0.5 max-w-full">
+              <a
+                href={bookUrl || pageUrl}
+                target="_blank"
+                rel="noopener noreferrer"
+                onClick={(e) => handleExternalClick(e, bookUrl || pageUrl)}
+                className="inline-flex items-center gap-1 text-xs text-primary-600 dark:text-primary-400 hover:underline min-w-0"
+              >
+                {isbn ? (
+                  <BookOpen size={10} className="flex-shrink-0" />
+                ) : (
+                  <ExternalLink size={10} className="flex-shrink-0" />
+                )}
+                <span className="truncate">
+                  {isbn ? bookTitle : displayUrl}
+                </span>
+              </a>
+              {isbn && bookPage && (
+                <span className="flex-shrink-0 text-xs text-surface-500 dark:text-surface-400">
+                  (p.{bookPage})
+                </span>
               )}
-              <span className="truncate">{isbn ? bookTitle : displayUrl}</span>
-            </a>
+            </div>
           )}
         </div>
       </div>
@@ -689,7 +740,7 @@ export default function Card({
         )}
 
         {!(contentWarning && !contentRevealed) &&
-          item.target?.selector?.exact && (
+          asTextQuote(item.target?.selector)?.exact && (
             <blockquote
               className={clsx(
                 "pl-4 py-2 border-l-[3px] mb-3 text-[15px] italic text-surface-600 dark:text-surface-300 rounded-r-lg hover:bg-surface-50 dark:hover:bg-surface-800/50 transition-colors",
@@ -726,7 +777,7 @@ export default function Card({
                 }}
                 className="block break-words"
               >
-                "{item.target?.selector?.exact}"
+                "{asTextQuote(item.target?.selector)?.exact}"
               </a>
             </blockquote>
           )}
diff --git a/web/src/components/feed/Composer.tsx b/web/src/components/feed/Composer.tsx
@@ -8,6 +8,7 @@ import {
   getTrendingTags,
 } from "../../api/client";
 import type { Selector, ContentLabelValue } from "../../types";
+import { asTextQuote } from "../../types";
 import { X, ShieldAlert, Highlighter, PenLine } from "lucide-react";
 import TagInput from "../ui/TagInput";
 import { analytics } from "../../lib/analytics";
@@ -114,17 +115,14 @@ export default function Composer({
         };
       }
 
+      const quoteSelector = asTextQuote(finalSelector);
       const tagList = tags.filter(Boolean);
 
       if (!text.trim()) {
-        if (!finalSelector) throw new Error("No text selected");
+        if (!quoteSelector) throw new Error("No text selected");
         await createHighlight({
           url,
-          selector: finalSelector as {
-            exact: string;
-            prefix?: string;
-            suffix?: string;
-          },
+          selector: quoteSelector,
           color: "yellow",
           tags: tagList,
           labels: selfLabels.length > 0 ? selfLabels : undefined,
@@ -139,13 +137,13 @@ export default function Composer({
         await createAnnotation({
           url,
           text: text.trim(),
-          selector: finalSelector || undefined,
+          selector: quoteSelector,
           tags: tagList,
           labels: selfLabels.length > 0 ? selfLabels : undefined,
         });
         analytics.capture("annotation_created", {
           url,
-          has_quote: !!finalSelector,
+          has_quote: !!quoteSelector,
           tag_count: tagList.length,
           has_labels: selfLabels.length > 0,
         });
diff --git a/web/src/components/modals/EditItemModal.tsx b/web/src/components/modals/EditItemModal.tsx
@@ -10,6 +10,7 @@ import {
   getTrendingTags,
 } from "../../api/client";
 import type { AnnotationItem, ContentLabelValue } from "../../types";
+import { asTextQuote } from "../../types";
 import TagInput from "../ui/TagInput";
 
 const SELF_LABEL_VALUES: ContentLabelValue[] = [
@@ -236,9 +237,9 @@ function EditItemModalContent({
                   />
                 ))}
               </div>
-              {item.target?.selector?.exact && (
+              {asTextQuote(item.target?.selector)?.exact && (
                 <blockquote className="mt-3 pl-3 py-2 border-l-2 border-surface-300 dark:border-surface-600 text-sm italic text-surface-500 dark:text-surface-400">
-                  {item.target.selector.exact}
+                  {asTextQuote(item.target?.selector)?.exact}
                 </blockquote>
               )}
             </div>
diff --git a/web/src/env.d.ts b/web/src/env.d.ts
@@ -1,5 +1,10 @@
 /// <reference types="astro/client" />
 
+declare module "virtual:lexicons" {
+  /** Raw lexicon JSON text, keyed by NSID id (e.g. "at.margin.note"). */
+  export const lexicons: Record<string, string>;
+}
+
 declare module "virtual:i18n-resources" {
   export const resources: Record<
     string,
diff --git a/web/src/pages/docs/specs/physical-books.astro b/web/src/pages/docs/specs/physical-books.astro
diff --git a/web/src/types.ts b/web/src/types.ts
diff --git a/web/src/views/About.tsx b/web/src/views/About.tsx
diff --git a/web/src/views/core/HighlightImporter.tsx b/web/src/views/core/HighlightImporter.tsx
diff --git a/web/src/views/core/Notifications.tsx b/web/src/views/core/Notifications.tsx
