@gmickel/gno 1.30.6 → 1.31.0

package/src/serve/public/lib/section-links.ts

@@ -0,0 +1,189 @@
+/**
+ * Readable section deep links and optional citation-safe selectors.
+ *
+ * Copy-link stays human-readable (`#anchor` only). Citation links add a
+ * bounded, versioned `st` query param for conservative recovery.
+ *
+ * @module src/serve/public/lib/section-links
+ */
+
+import {
+  createSectionTarget,
+  decodeSectionTargetLinkParam,
+  encodeSectionTargetLinkParam,
+  isNavigableSectionResolution,
+  resolveSectionTarget,
+  SECTION_TARGET_LINK_PARAM,
+  type SectionResolutionStatus,
+  type SectionTargetV1,
+} from "../../../core/sections";
+import { buildDocDeepLink, type DocumentDeepLinkTarget } from "./deep-links";
+
+export interface SectionLinkTarget extends DocumentDeepLinkTarget {
+  /** Readable heading anchor (HTML id). */
+  anchor: string;
+}
+
+export type SectionLinkNoticeKind =
+  | "copied_link"
+  | "copied_citation"
+  | "citation_unavailable"
+  | "clipboard_unavailable"
+  | SectionResolutionStatus
+  | "invalid_citation";
+
+/** Ephemeral, content-free status copy for outline/rail feedback. */
+export const SECTION_LINK_NOTICE_COPY: Record<SectionLinkNoticeKind, string> = {
+  copied_link: "Copied section link",
+  copied_citation: "Copied citation link",
+  citation_unavailable: "Citation unavailable for this section",
+  clipboard_unavailable: "Could not copy link",
+  exact: "Exact section match",
+  recovered: "Section recovered",
+  ambiguous: "Ambiguous section link — not navigating",
+  stale: "Stale section link — not navigating",
+  missing: "Section link not found — not navigating",
+  invalid_citation: "Invalid section citation — not navigating",
+};
+
+/** Absolute readable section URL for human sharing (no durable selector). */
+export function buildReadableSectionUrl(
+  origin: string,
+  target: SectionLinkTarget
+): string {
+  const path = `${buildDocDeepLink({
+    uri: target.uri,
+    view: target.view ?? "rendered",
+  })}#${target.anchor}`;
+  return `${origin}${path}`;
+}
+
+/**
+ * Absolute citation URL: readable `#anchor` plus bounded `st` selector.
+ * Returns null when a faithful bounded encoding cannot be produced.
+ */
+export function buildCitationSectionUrl(
+  origin: string,
+  target: SectionLinkTarget,
+  sectionTarget: SectionTargetV1
+): string | null {
+  const encoded = encodeSectionTargetLinkParam(sectionTarget);
+  if (!encoded) {
+    return null;
+  }
+  const params = new URLSearchParams({ uri: target.uri });
+  params.set("view", target.view ?? "rendered");
+  params.set(SECTION_TARGET_LINK_PARAM, encoded);
+  return `${origin}/doc?${params.toString()}#${target.anchor}`;
+}
+
+/** Read the raw `st` query value from a location search string. */
+export function readSectionTargetLinkParam(search: string): string | null {
+  const value = new URLSearchParams(search).get(SECTION_TARGET_LINK_PARAM);
+  return value && value.length > 0 ? value : null;
+}
+
+/** Strip the additive `st` param while preserving other query fields. */
+export function stripSectionTargetLinkParam(search: string): string {
+  const params = new URLSearchParams(
+    search.startsWith("?") ? search.slice(1) : search
+  );
+  params.delete(SECTION_TARGET_LINK_PARAM);
+  const serialized = params.toString();
+  return serialized.length > 0 ? `?${serialized}` : "";
+}
+
+export interface ResolveSectionLinkInput {
+  content: string;
+  uri: string;
+  /** Raw `st` query value. */
+  encodedTarget: string | null;
+  /** Readable hash without leading `#`. */
+  hashAnchor: string;
+}
+
+export interface ResolveSectionLinkResult {
+  /** When true, hash-only scroll must not run. */
+  blockHashNavigation: boolean;
+  /** Anchor to scroll to when navigable. */
+  navigateAnchor: string | null;
+  notice: SectionLinkNoticeKind | null;
+  /** Drop `st` from the address bar after a successful recovery. */
+  cleanCitationParam: boolean;
+}
+
+/**
+ * Resolve an optional durable selector against current document content.
+ * Readable `#anchor`-only links keep legacy behavior (no block).
+ */
+export async function resolveSectionLinkNavigation(
+  input: ResolveSectionLinkInput
+): Promise<ResolveSectionLinkResult> {
+  if (!input.encodedTarget) {
+    return {
+      blockHashNavigation: false,
+      navigateAnchor: input.hashAnchor || null,
+      notice: null,
+      cleanCitationParam: false,
+    };
+  }
+
+  const target = decodeSectionTargetLinkParam(input.encodedTarget);
+  if (!target) {
+    return {
+      blockHashNavigation: true,
+      navigateAnchor: null,
+      notice: "invalid_citation",
+      cleanCitationParam: false,
+    };
+  }
+
+  const resolution = await resolveSectionTarget({
+    content: input.content,
+    target,
+    uri: input.uri,
+  });
+
+  if (isNavigableSectionResolution(resolution)) {
+    return {
+      blockHashNavigation: false,
+      navigateAnchor: resolution.section.anchor,
+      notice: resolution.status,
+      cleanCitationParam: true,
+    };
+  }
+
+  return {
+    blockHashNavigation: true,
+    navigateAnchor: null,
+    notice: resolution.status,
+    cleanCitationParam: false,
+  };
+}
+
+/** Create a citation URL for an outline section using shared core create. */
+export async function createCitationSectionUrl(input: {
+  origin: string;
+  uri: string;
+  content: string;
+  anchor: string;
+  view?: "rendered" | "source";
+}): Promise<string | null> {
+  const target = await createSectionTarget({
+    content: input.content,
+    uri: input.uri,
+    anchor: input.anchor,
+  });
+  if (!target) {
+    return null;
+  }
+  return buildCitationSectionUrl(
+    input.origin,
+    {
+      uri: input.uri,
+      view: input.view ?? "rendered",
+      anchor: input.anchor,
+    },
+    target
+  );
+}

package/src/serve/public/pages/DocView.tsx

@@ -13,6 +13,7 @@ import {
   LinkIcon,
   Loader2Icon,
   PencilIcon,
+  QuoteIcon,
   Share2Icon,
   SquareArrowOutUpRightIcon,
   TextIcon,
@@ -83,6 +84,15 @@ import {
   downloadPublishArtifactFile,
   type PublishExportResponse,
 } from "../lib/publish-export";
+import {
+  buildReadableSectionUrl,
+  createCitationSectionUrl,
+  readSectionTargetLinkParam,
+  resolveSectionLinkNavigation,
+  SECTION_LINK_NOTICE_COPY,
+  stripSectionTargetLinkParam,
+  type SectionLinkNoticeKind,
+} from "../lib/section-links";
 import { subscribeWorkspaceActionRequest } from "../lib/workspace-events";
 
 /** Lazy so pdfjs is never pulled for non-PDF documents. */
@@ -389,9 +399,13 @@ export default function DocView({ navigate }: PageProps) {
   const [activeSectionAnchor, setActiveSectionAnchor] = useState<string | null>(
     null
   );
+  const [sectionLinkNotice, setSectionLinkNotice] =
+    useState<SectionLinkNoticeKind | null>(null);
+  const [blockHashNavigation, setBlockHashNavigation] = useState(false);
 
   // Request sequencing - ignore stale responses on rapid navigation
   const requestIdRef = useRef(0);
+  const sectionResolveRequestRef = useRef(0);
   const latestDocEvent = useDocEvents();
 
   // App remounts page on route/query changes, so URI is stable per render.
@@ -404,6 +418,10 @@ export default function DocView({ navigate }: PageProps) {
     () => window.location.hash.replace(/^#/u, ""),
     []
   );
+  const encodedSectionTarget = useMemo(
+    () => readSectionTargetLinkParam(window.location.search),
+    []
+  );
   const highlightedLines = useMemo(() => {
     if (!currentTarget.lineStart) return [];
     const end = currentTarget.lineEnd ?? currentTarget.lineStart;
@@ -564,7 +582,78 @@ export default function DocView({ navigate }: PageProps) {
   }, []);
 
   useEffect(() => {
-    if (!currentHash || showRawView || loading) {
+    if (!sectionLinkNotice) {
+      return;
+    }
+    const timer = window.setTimeout(() => setSectionLinkNotice(null), 3200);
+    return () => {
+      window.clearTimeout(timer);
+    };
+  }, [sectionLinkNotice]);
+
+  useEffect(() => {
+    if (!doc?.content || loading || !encodedSectionTarget) {
+      return;
+    }
+
+    const requestId = ++sectionResolveRequestRef.current;
+    const content = doc.content;
+    void resolveSectionLinkNavigation({
+      content,
+      uri: doc.uri,
+      encodedTarget: encodedSectionTarget,
+      hashAnchor: currentHash,
+    }).then((result) => {
+      if (requestId !== sectionResolveRequestRef.current) {
+        return;
+      }
+      setBlockHashNavigation(result.blockHashNavigation);
+      if (result.notice) {
+        setSectionLinkNotice(result.notice);
+      }
+      if (result.cleanCitationParam) {
+        const cleanedSearch = stripSectionTargetLinkParam(
+          window.location.search
+        );
+        const nextHash = result.navigateAnchor
+          ? `#${result.navigateAnchor}`
+          : window.location.hash;
+        window.history.replaceState(
+          {},
+          "",
+          `${window.location.pathname}${cleanedSearch}${nextHash}`
+        );
+      }
+      if (result.blockHashNavigation || !result.navigateAnchor) {
+        return;
+      }
+      if (showRawView) {
+        return;
+      }
+      requestAnimationFrame(() => {
+        document
+          .getElementById(result.navigateAnchor ?? "")
+          ?.scrollIntoView({ behavior: "smooth", block: "start" });
+        setActiveSectionAnchor(result.navigateAnchor);
+      });
+    });
+  }, [
+    currentHash,
+    doc?.content,
+    doc?.uri,
+    encodedSectionTarget,
+    loading,
+    showRawView,
+  ]);
+
+  useEffect(() => {
+    if (
+      blockHashNavigation ||
+      encodedSectionTarget ||
+      !currentHash ||
+      showRawView ||
+      loading
+    ) {
       return;
     }
 
@@ -574,7 +663,13 @@ export default function DocView({ navigate }: PageProps) {
         ?.scrollIntoView({ behavior: "smooth", block: "start" });
       setActiveSectionAnchor(currentHash);
     });
-  }, [currentHash, loading, showRawView]);
+  }, [
+    blockHashNavigation,
+    currentHash,
+    encodedSectionTarget,
+    loading,
+    showRawView,
+  ]);
 
   const breadcrumbs = doc ? parseBreadcrumbs(doc.collection, doc.relPath) : [];
   const sections = useMemo(
@@ -582,6 +677,79 @@ export default function DocView({ navigate }: PageProps) {
     [parsedContent.body]
   );
 
+  const copyReadableSectionLink = useCallback(
+    (anchor: string) => {
+      if (!doc) {
+        return;
+      }
+      void navigator.clipboard
+        .writeText(
+          buildReadableSectionUrl(window.location.origin, {
+            uri: doc.uri,
+            view: "rendered",
+            anchor,
+          })
+        )
+        .then(() => {
+          setSectionLinkNotice("copied_link");
+        })
+        .catch(() => {
+          setSectionLinkNotice("clipboard_unavailable");
+        });
+    },
+    [doc]
+  );
+
+  const copyCitationSectionLink = useCallback(
+    async (anchor: string) => {
+      const content = doc?.content;
+      if (!doc || !content) {
+        return;
+      }
+      const citationUrl = await createCitationSectionUrl({
+        origin: window.location.origin,
+        uri: doc.uri,
+        content,
+        anchor,
+        view: "rendered",
+      });
+      if (!citationUrl) {
+        setSectionLinkNotice("citation_unavailable");
+        return;
+      }
+      try {
+        await navigator.clipboard.writeText(citationUrl);
+        setSectionLinkNotice("copied_citation");
+      } catch {
+        setSectionLinkNotice("clipboard_unavailable");
+      }
+    },
+    [doc]
+  );
+
+  const jumpToSection = useCallback(
+    (anchor: string) => {
+      setShowRawView(false);
+      setBlockHashNavigation(false);
+      requestAnimationFrame(() => {
+        document.getElementById(anchor)?.scrollIntoView({
+          behavior: "smooth",
+          block: "start",
+        });
+        window.history.replaceState(
+          {},
+          "",
+          `${buildDocDeepLink({
+            uri: doc?.uri ?? "",
+            view: "rendered",
+          })}#${anchor}`
+        );
+        setActiveSectionAnchor(anchor);
+      });
+    },
+    [doc?.uri]
+  );
+
   useEffect(() => {
     if (showRawView || sections.length === 0) {
       setActiveSectionAnchor(sections[0]?.anchor ?? null);
@@ -1170,8 +1338,19 @@ export default function DocView({ navigate }: PageProps) {
         <>
           <div className="mx-3 border-border/20 border-t" />
           <div className="px-3 py-3">
-            <div className="mb-2 font-mono text-[10px] text-muted-foreground/50 uppercase tracking-[0.15em]">
-              Outline
+            <div className="mb-2 flex items-center justify-between gap-2">
+              <div className="font-mono text-[10px] text-muted-foreground/50 uppercase tracking-[0.15em]">
+                Outline
+              </div>
+              {sectionLinkNotice && (
+                <div
+                  aria-live="polite"
+                  className="min-w-0 truncate font-mono text-[10px] text-muted-foreground/70"
+                  role="status"
+                >
+                  {SECTION_LINK_NOTICE_COPY[sectionLinkNotice]}
+                </div>
+              )}
             </div>
             <div className="w-full min-w-0 max-w-full space-y-0.5 overflow-x-hidden">
               {sections.map((section) => (
@@ -1185,25 +1364,9 @@ export default function DocView({ navigate }: PageProps) {
                   style={{ paddingLeft: `${section.level * 7}px` }}
                 >
                   <button
-                    className="flex w-full min-w-0 max-w-full cursor-pointer items-start gap-2 overflow-hidden rounded px-1 py-0.5 pr-7 text-left text-xs transition-colors hover:bg-muted/20 hover:text-foreground"
+                    className="flex w-full min-w-0 max-w-full cursor-pointer items-start gap-2 overflow-hidden rounded px-1 py-0.5 pr-12 text-left text-xs transition-colors hover:bg-muted/20 hover:text-foreground"
                     onClick={() => {
-                      setShowRawView(false);
-                      requestAnimationFrame(() => {
-                        document
-                          .getElementById(section.anchor)
-                          ?.scrollIntoView({
-                            behavior: "smooth",
-                            block: "start",
-                          });
-                        window.history.replaceState(
-                          {},
-                          "",
-                          `${buildDocDeepLink({
-                            uri: doc?.uri ?? "",
-                            view: "rendered",
-                          })}#${section.anchor}`
-                        );
-                      });
+                      jumpToSection(section.anchor);
                     }}
                     type="button"
                   >
@@ -1221,20 +1384,40 @@ export default function DocView({ navigate }: PageProps) {
                       </TooltipContent>
                     </Tooltip>
                   </button>
-                  <button
-                    className="absolute top-1 right-1 cursor-pointer rounded p-1 opacity-0 transition-all hover:bg-muted/20 hover:text-foreground focus-visible:opacity-100 group-hover:opacity-100"
-                    onClick={() => {
-                      void navigator.clipboard.writeText(
-                        `${window.location.origin}${buildDocDeepLink({
-                          uri: doc?.uri ?? "",
-                          view: "rendered",
-                        })}#${section.anchor}`
-                      );
-                    }}
-                    type="button"
-                  >
-                    <CopyIcon className="size-3" />
-                  </button>
+                  <div className="absolute top-1 right-1 flex items-center gap-0.5 opacity-0 transition-all focus-within:opacity-100 group-hover:opacity-100">
+                    <Tooltip>
+                      <TooltipTrigger asChild>
+                        <button
+                          aria-label={`Copy link to ${section.title}`}
+                          className="cursor-pointer rounded p-1 hover:bg-muted/20 hover:text-foreground"
+                          onClick={() => {
+                            copyReadableSectionLink(section.anchor);
+                          }}
+                          type="button"
+                        >
+                          <CopyIcon className="size-3" />
+                        </button>
+                      </TooltipTrigger>
+                      <TooltipContent side="left">Copy link</TooltipContent>
+                    </Tooltip>
+                    <Tooltip>
+                      <TooltipTrigger asChild>
+                        <button
+                          aria-label={`Copy local citation link to ${section.title}`}
+                          className="cursor-pointer rounded p-1 hover:bg-muted/20 hover:text-foreground"
+                          onClick={() => {
+                            void copyCitationSectionLink(section.anchor);
+                          }}
+                          type="button"
+                        >
+                          <QuoteIcon className="size-3" />
+                        </button>
+                      </TooltipTrigger>
+                      <TooltipContent side="left">
+                        Copy local citation link
+                      </TooltipContent>
+                    </Tooltip>
+                  </div>
                 </div>
               ))}
             </div>