spaps-issue-reporting-react 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [0.1.1] - 2026-04-05
+
+- Docs: align package README metadata with published version.
+
 ## [0.1.0] - 2026-03-29
 
 - Added the first shared React issue-reporting package for SPAPS consumers.

package/README.md

@@ -17,9 +17,9 @@ This package targets `Node.js >=18` and React 18+.
 | Need | Package gives you |
 | --- | --- |
 | A visible issue-report entry point | Floating button with open/recent state |
-| A guided reporting flow | Report mode, highlighted sections, create/edit/reply modal |
+| A guided reporting flow | Page-first create flow, optional section picking, create/edit/reply modal |
 | A lightweight integration contract | Any client that exposes `issueReporting.*` methods |
-| App-level control | Eligibility, reporter identity, scope, and copy stay in your app |
+| App-level control | Eligibility, reporter identity, scope, page policy, and copy stay in your app |
 
 ## Quick Start
 
@@ -27,6 +27,7 @@ This package targets `Node.js >=18` and React 18+.
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import {
   FloatingIssueReportButton,
+  IssueReportingPageConfig,
   IssueReportingProvider,
   ReportableSection,
 } from "spaps-issue-reporting-react";
@@ -45,6 +46,8 @@ export function AppShell() {
         allowTenantScope
         defaultScope="mine"
       >
+        <IssueReportingPageConfig createMode="surface_preferred" />
+
         <ReportableSection
           reportableName={{
             componentKey: "patient_chart",
@@ -66,20 +69,26 @@ export function AppShell() {
 ## What Your App Still Owns
 
 - A client with `issueReporting.getStatus`, `list`, `get`, `create`, `update`, and `reply`.
+- Any auth and token refresh behavior needed by that client.
 - Eligibility rules such as feature flags, account state, or role checks.
 - The current principal ID and optional role hint passed into the provider.
 - Whether users can switch between `mine` and `tenant` queue scope.
+- Whether a page defaults to `general_page`, `surface_required`, or `surface_preferred` reporting.
 - Styling integration if your build strips package utility classes.
 - Any app-specific copy overrides.
+- Origin registration on the owning SPAPS application if the browser calls SPAPS directly with a publishable key.
+
+For direct browser integrations, `allowed_origins` is stored on the SPAPS `applications` row that owns the publishable key. It is not configured on this package. If multiple hostnames share one SPAPS application, put all of them on that row. Updating `allowed_origins` does not require restarting SPAPS.
 
 ## Exported Surface
 
 | Export | Purpose |
 | --- | --- |
 | `IssueReportingProvider` | Owns queries, modal state, copy, scope, and report-mode behavior |
+| `IssueReportingPageConfig` | Per-page override for `general_page`, `surface_required`, or `surface_preferred` create policy |
 | `FloatingIssueReportButton` | Renders the floating entry point, popover, and modal |
 | `ReportableSection` | Marks a region as selectable when report mode is active |
-| `useIssueReporting` | Full provider state, including `enterReportMode()` |
+| `useIssueReporting` | Full provider state, including `startNewIssue()`, `openPageIssueModal()`, and `enterReportMode()` |
 | `useIssueReportingStatus` | Query helper for summary state |
 | `useIssueReportingHistory` | Query helper for filtered history lists |
 | `useIssueReportingMutations` | Mutation helpers for create, update, and reply flows |
@@ -107,10 +116,18 @@ npm test
 
 Make sure `FloatingIssueReportButton` is rendered inside `IssueReportingProvider` and that `isEligible` is `true`.
 
+### I want page-level reporting without wrapping every widget
+
+That is the default. `Report This Page` opens immediately and captures the current route plus the inventory of visible registered reportable sections on the active page.
+
 ### Report mode turns on, but sections do not respond
 
 Wrap the target UI in `ReportableSection`, or call `useIssueReporting().selectPanel(...)` from a custom control.
 
+### This page should force a specific surface selection
+
+Render `IssueReportingPageConfig` with `createMode="surface_required"` inside that page's visible provider subtree. Hidden mounted routes, tabs, or panels do not affect the active page's policy.
+
 ### Tenant scope never appears
 
 Set `allowTenantScope={true}`. The provider defaults to `mine`.
@@ -135,6 +152,10 @@ No. You only need a client object that implements the `issueReporting` methods e
 
 Yes. Use `useIssueReporting().enterReportMode()` inside the provider tree.
 
+### Can I open a page-level report from my own button?
+
+Yes. Use `useIssueReporting().openPageIssueModal()` or `useIssueReporting().startNewIssue()`.
+
 ### Can I report plain strings instead of structured descriptors?
 
 Yes. `reportableName` accepts either a string or a `{ componentKey, componentLabel, ... }` object.
@@ -147,6 +168,17 @@ Yes. Drive that from `isEligible`.
 
 No. It only renders scope choices that your app explicitly allows.
 
+### Does this package manage CORS or `allowed_origins`?
+
+No. This package is UI only. If your browser app calls SPAPS directly with a publishable key, the relevant SPAPS application row must include that browser origin in `allowed_origins`.
+
+## Metadata
+
+- `package_name`: `spaps-issue-reporting-react`
+- `latest_version`: `0.1.1`
+- `minimum_runtime`: `Node.js >=18.0.0`
+- `api_base_url`: `https://api.sweetpotato.dev`
+
 ## About Contributions
 
 > *About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.

package/dist/index.d.mts

@@ -31,11 +31,14 @@ interface ReportableTargetDescriptor {
     metadata?: Record<string, unknown>;
 }
 type ReportableInput = string | ReportableTargetDescriptor;
+type IssueReportingCreateMode = "general_page" | "surface_required" | "surface_preferred";
 type IssueHistoryFilter = "all" | "unresolved" | "resolved";
 interface IssueReportingCopy {
     entryAriaLabel: string;
     popoverTitle: string;
     reportNewAction: string;
+    reportPageAction: string;
+    reportSpecificAction: string;
     filtersAll: string;
     filtersUnresolved: string;
     filtersResolved: string;
@@ -52,6 +55,9 @@ interface IssueReportingCopy {
     reportModeTitle: string;
     reportModeDescription: string;
     reportModeCancelAction: string;
+    generalPageTargetLabel: string;
+    surfaceRequiredDescription: string;
+    specificSectionUnavailableDescription: string;
     createTitlePrefix: string;
     editTitlePrefix: string;
     replyTitlePrefix: string;
@@ -82,6 +88,7 @@ interface IssueReportingProviderProps {
     getPageUrl?: () => string;
     defaultScope?: IssueReportScope;
     allowTenantScope?: boolean;
+    defaultCreateMode?: IssueReportingCreateMode;
     copy?: Partial<IssueReportingCopy>;
     children: ReactNode;
 }
@@ -89,6 +96,9 @@ interface FloatingIssueReportButtonProps {
     className?: string;
     positionClassName?: string;
 }
+interface IssueReportingPageConfigProps {
+    createMode: IssueReportingCreateMode;
+}
 
 declare function FloatingIssueReportButton({ className, positionClassName, }: FloatingIssueReportButtonProps): react_jsx_runtime.JSX.Element | null;
 declare function ReportableSection({ reportableName, children, className, as: Component, }: {
@@ -96,7 +106,7 @@ declare function ReportableSection({ reportableName, children, className, as: Co
     children: React__default.ReactNode;
     className?: string;
     as?: keyof JSX.IntrinsicElements;
-}): react_jsx_runtime.JSX.Element;
+}): React__default.ReactElement<any, string | React__default.JSXElementConstructor<any>>;
 
 type ModalMode = "create" | "edit" | "reply";
 type ResolvedTarget = {
@@ -122,9 +132,12 @@ type IssueReportingContextValue = {
     principalId: string | null;
     copy: IssueReportingCopy;
     isReportMode: boolean;
+    hasRegisteredTargets: boolean;
     enterReportMode: () => void;
     cancelReportMode: () => void;
     selectPanel: (target: ReportableInput) => void;
+    openPageIssueModal: () => void;
+    startNewIssue: () => void;
     isPopoverOpen: boolean;
     openPopover: () => void;
     closePopover: () => void;
@@ -135,6 +148,7 @@ type IssueReportingContextValue = {
     scope: IssueReportScope;
     setScope: (scope: IssueReportScope) => void;
     allowTenantScope: boolean;
+    createMode: IssueReportingCreateMode;
 };
 declare const defaultIssueReportingCopy: IssueReportingCopy;
 declare const issueReportingKeys: {
@@ -155,6 +169,7 @@ declare function getEntryPointState(status?: {
 declare function getEntryPointClassName(state: "open" | "recent_resolved" | "neutral"): string;
 declare function getIssueNoteLengthMessage(note: string, copy: IssueReportingCopy): string;
 declare function useIssueReporting(): IssueReportingContextValue;
+declare function IssueReportingPageConfig({ createMode, }: IssueReportingPageConfigProps): react_jsx_runtime.JSX.Element;
 declare function useIssueReportingStatus(): _tanstack_react_query.UseQueryResult<spaps_types.IssueReportStatusResult, Error>;
 declare function useIssueReportingHistory(filter?: IssueHistoryFilter): {
     items: IssueReport[];
@@ -347,14 +362,17 @@ declare function useIssueReportingMutations(): {
         reporterRoleHint?: string;
     }, unknown>;
 };
-declare function IssueReportingProvider({ client, isEligible, reporterRoleHint, principalId, getPageUrl, defaultScope, allowTenantScope, copy, children, }: IssueReportingProviderProps): react_jsx_runtime.JSX.Element;
+declare function IssueReportingProvider({ client, isEligible, reporterRoleHint, principalId, getPageUrl, defaultScope, allowTenantScope, defaultCreateMode, copy, children, }: IssueReportingProviderProps): react_jsx_runtime.JSX.Element;
 
 interface ReportModeContextValue {
     isReportMode: boolean;
     selectPanel: (target: ReportableInput) => void;
     cancelReportMode: () => void;
+    hasRegisteredTargets: boolean;
+    registerTarget: (id: symbol, target: ReportableInput, getElement: () => Element | null) => void;
+    unregisterTarget: (id: symbol) => void;
 }
 declare const ReportModeContext: React.Context<ReportModeContextValue | null>;
 declare function useReportMode(): ReportModeContextValue | null;
 
-export { FloatingIssueReportButton, type FloatingIssueReportButtonProps, type IssueHistoryFilter, type IssueReportingClient, type IssueReportingCopy, IssueReportingProvider, type IssueReportingProviderProps, ReportModeContext, type ReportModeContextValue, type ReportableInput, ReportableSection, type ReportableTargetDescriptor, defaultIssueReportingCopy, filterIssueReports, getEntryPointClassName, getEntryPointState, getIssueNoteLengthMessage, getIssueStatusBadgeLabel, getIssueStatusClassName, isClosedIssueStatus, isOpenIssueStatus, issueReportingKeys, useIssueReporting, useIssueReportingHistory, useIssueReportingMutations, useIssueReportingStatus, useReportMode };
+export { FloatingIssueReportButton, type FloatingIssueReportButtonProps, type IssueHistoryFilter, type IssueReportingClient, type IssueReportingCopy, type IssueReportingCreateMode, IssueReportingPageConfig, type IssueReportingPageConfigProps, IssueReportingProvider, type IssueReportingProviderProps, ReportModeContext, type ReportModeContextValue, type ReportableInput, ReportableSection, type ReportableTargetDescriptor, defaultIssueReportingCopy, filterIssueReports, getEntryPointClassName, getEntryPointState, getIssueNoteLengthMessage, getIssueStatusBadgeLabel, getIssueStatusClassName, isClosedIssueStatus, isOpenIssueStatus, issueReportingKeys, useIssueReporting, useIssueReportingHistory, useIssueReportingMutations, useIssueReportingStatus, useReportMode };

package/dist/index.d.ts

@@ -31,11 +31,14 @@ interface ReportableTargetDescriptor {
     metadata?: Record<string, unknown>;
 }
 type ReportableInput = string | ReportableTargetDescriptor;
+type IssueReportingCreateMode = "general_page" | "surface_required" | "surface_preferred";
 type IssueHistoryFilter = "all" | "unresolved" | "resolved";
 interface IssueReportingCopy {
     entryAriaLabel: string;
     popoverTitle: string;
     reportNewAction: string;
+    reportPageAction: string;
+    reportSpecificAction: string;
     filtersAll: string;
     filtersUnresolved: string;
     filtersResolved: string;
@@ -52,6 +55,9 @@ interface IssueReportingCopy {
     reportModeTitle: string;
     reportModeDescription: string;
     reportModeCancelAction: string;
+    generalPageTargetLabel: string;
+    surfaceRequiredDescription: string;
+    specificSectionUnavailableDescription: string;
     createTitlePrefix: string;
     editTitlePrefix: string;
     replyTitlePrefix: string;
@@ -82,6 +88,7 @@ interface IssueReportingProviderProps {
     getPageUrl?: () => string;
     defaultScope?: IssueReportScope;
     allowTenantScope?: boolean;
+    defaultCreateMode?: IssueReportingCreateMode;
     copy?: Partial<IssueReportingCopy>;
     children: ReactNode;
 }
@@ -89,6 +96,9 @@ interface FloatingIssueReportButtonProps {
     className?: string;
     positionClassName?: string;
 }
+interface IssueReportingPageConfigProps {
+    createMode: IssueReportingCreateMode;
+}
 
 declare function FloatingIssueReportButton({ className, positionClassName, }: FloatingIssueReportButtonProps): react_jsx_runtime.JSX.Element | null;
 declare function ReportableSection({ reportableName, children, className, as: Component, }: {
@@ -96,7 +106,7 @@ declare function ReportableSection({ reportableName, children, className, as: Co
     children: React__default.ReactNode;
     className?: string;
     as?: keyof JSX.IntrinsicElements;
-}): react_jsx_runtime.JSX.Element;
+}): React__default.ReactElement<any, string | React__default.JSXElementConstructor<any>>;
 
 type ModalMode = "create" | "edit" | "reply";
 type ResolvedTarget = {
@@ -122,9 +132,12 @@ type IssueReportingContextValue = {
     principalId: string | null;
     copy: IssueReportingCopy;
     isReportMode: boolean;
+    hasRegisteredTargets: boolean;
     enterReportMode: () => void;
     cancelReportMode: () => void;
     selectPanel: (target: ReportableInput) => void;
+    openPageIssueModal: () => void;
+    startNewIssue: () => void;
     isPopoverOpen: boolean;
     openPopover: () => void;
     closePopover: () => void;
@@ -135,6 +148,7 @@ type IssueReportingContextValue = {
     scope: IssueReportScope;
     setScope: (scope: IssueReportScope) => void;
     allowTenantScope: boolean;
+    createMode: IssueReportingCreateMode;
 };
 declare const defaultIssueReportingCopy: IssueReportingCopy;
 declare const issueReportingKeys: {
@@ -155,6 +169,7 @@ declare function getEntryPointState(status?: {
 declare function getEntryPointClassName(state: "open" | "recent_resolved" | "neutral"): string;
 declare function getIssueNoteLengthMessage(note: string, copy: IssueReportingCopy): string;
 declare function useIssueReporting(): IssueReportingContextValue;
+declare function IssueReportingPageConfig({ createMode, }: IssueReportingPageConfigProps): react_jsx_runtime.JSX.Element;
 declare function useIssueReportingStatus(): _tanstack_react_query.UseQueryResult<spaps_types.IssueReportStatusResult, Error>;
 declare function useIssueReportingHistory(filter?: IssueHistoryFilter): {
     items: IssueReport[];
@@ -347,14 +362,17 @@ declare function useIssueReportingMutations(): {
         reporterRoleHint?: string;
     }, unknown>;
 };
-declare function IssueReportingProvider({ client, isEligible, reporterRoleHint, principalId, getPageUrl, defaultScope, allowTenantScope, copy, children, }: IssueReportingProviderProps): react_jsx_runtime.JSX.Element;
+declare function IssueReportingProvider({ client, isEligible, reporterRoleHint, principalId, getPageUrl, defaultScope, allowTenantScope, defaultCreateMode, copy, children, }: IssueReportingProviderProps): react_jsx_runtime.JSX.Element;
 
 interface ReportModeContextValue {
     isReportMode: boolean;
     selectPanel: (target: ReportableInput) => void;
     cancelReportMode: () => void;
+    hasRegisteredTargets: boolean;
+    registerTarget: (id: symbol, target: ReportableInput, getElement: () => Element | null) => void;
+    unregisterTarget: (id: symbol) => void;
 }
 declare const ReportModeContext: React.Context<ReportModeContextValue | null>;
 declare function useReportMode(): ReportModeContextValue | null;
 
-export { FloatingIssueReportButton, type FloatingIssueReportButtonProps, type IssueHistoryFilter, type IssueReportingClient, type IssueReportingCopy, IssueReportingProvider, type IssueReportingProviderProps, ReportModeContext, type ReportModeContextValue, type ReportableInput, ReportableSection, type ReportableTargetDescriptor, defaultIssueReportingCopy, filterIssueReports, getEntryPointClassName, getEntryPointState, getIssueNoteLengthMessage, getIssueStatusBadgeLabel, getIssueStatusClassName, isClosedIssueStatus, isOpenIssueStatus, issueReportingKeys, useIssueReporting, useIssueReportingHistory, useIssueReportingMutations, useIssueReportingStatus, useReportMode };
+export { FloatingIssueReportButton, type FloatingIssueReportButtonProps, type IssueHistoryFilter, type IssueReportingClient, type IssueReportingCopy, type IssueReportingCreateMode, IssueReportingPageConfig, type IssueReportingPageConfigProps, IssueReportingProvider, type IssueReportingProviderProps, ReportModeContext, type ReportModeContextValue, type ReportableInput, ReportableSection, type ReportableTargetDescriptor, defaultIssueReportingCopy, filterIssueReports, getEntryPointClassName, getEntryPointState, getIssueNoteLengthMessage, getIssueStatusBadgeLabel, getIssueStatusClassName, isClosedIssueStatus, isOpenIssueStatus, issueReportingKeys, useIssueReporting, useIssueReportingHistory, useIssueReportingMutations, useIssueReportingStatus, useReportMode };

package/dist/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   FloatingIssueReportButton: () => FloatingIssueReportButton,
+  IssueReportingPageConfig: () => IssueReportingPageConfig,
   IssueReportingProvider: () => IssueReportingProvider,
   ReportModeContext: () => ReportModeContext,
   ReportableSection: () => ReportableSection,
@@ -57,7 +58,7 @@ var Dialog = __toESM(require("@radix-ui/react-dialog"));
 var Popover = __toESM(require("@radix-ui/react-popover"));
 var import_react3 = require("@phosphor-icons/react");
 var import_date_fns = require("date-fns");
-var import_react4 = require("react");
+var import_react4 = __toESM(require("react"));
 
 // src/provider.tsx
 var import_react2 = require("react");
@@ -89,10 +90,24 @@ var initialModalState = {
 var IssueReportingContext = (0, import_react2.createContext)(
   void 0
 );
+var IssueReportingPageConfigRegistryContext = (0, import_react2.createContext)(void 0);
+var hiddenMarkerStyle = {
+  position: "absolute",
+  width: "1px",
+  height: "1px",
+  padding: 0,
+  margin: "-1px",
+  overflow: "hidden",
+  clip: "rect(0, 0, 0, 0)",
+  whiteSpace: "nowrap",
+  border: 0
+};
 var defaultIssueReportingCopy = {
   entryAriaLabel: "Report issue",
   popoverTitle: "Issue Reports",
   reportNewAction: "Report New Issue",
+  reportPageAction: "Report This Page",
+  reportSpecificAction: "Pick Specific Section",
   filtersAll: "All",
   filtersUnresolved: "Unresolved",
   filtersResolved: "Resolved",
@@ -109,6 +124,9 @@ var defaultIssueReportingCopy = {
   reportModeTitle: "Report mode is active",
   reportModeDescription: "Click a highlighted section to capture the broken surface.",
   reportModeCancelAction: "Cancel",
+  generalPageTargetLabel: "Current Page",
+  surfaceRequiredDescription: "This page requires selecting a specific section before you submit a report.",
+  specificSectionUnavailableDescription: "No specific sections are registered on this page right now.",
   createTitlePrefix: "Report Issue",
   editTitlePrefix: "Edit Issue",
   replyTitlePrefix: "Reply to",
@@ -173,6 +191,44 @@ function normalizeTarget(target, getPageUrl) {
     metadata: target.metadata ?? {}
   };
 }
+function summarizeTarget(target) {
+  if (typeof target === "string") {
+    const normalized = target.trim();
+    return {
+      component_key: normalized,
+      component_label: normalized,
+      surface_ref: null,
+      metadata: {}
+    };
+  }
+  const key = target.componentKey.trim();
+  return {
+    component_key: key,
+    component_label: (target.componentLabel ?? key).trim(),
+    surface_ref: target.surfaceRef ?? null,
+    metadata: target.metadata ?? {}
+  };
+}
+function isElementVisibleForReporting(element) {
+  if (!element || typeof window === "undefined") {
+    return true;
+  }
+  let current = element;
+  while (current) {
+    if (current.getAttribute("aria-hidden") === "true") {
+      return false;
+    }
+    if (current instanceof HTMLElement && (current.hidden || current.inert)) {
+      return false;
+    }
+    const computedStyle = window.getComputedStyle(current);
+    if (computedStyle.display === "none" || computedStyle.visibility === "hidden" || computedStyle.visibility === "collapse") {
+      return false;
+    }
+    current = current.parentElement;
+  }
+  return true;
+}
 function normalizeIssueTarget(issue) {
   return {
     component_key: issue.target.component_key,
@@ -254,6 +310,23 @@ function getIssueNoteLengthMessage(note, copy) {
   }
   return `${note.length}/${NOTE_MAX_LENGTH}`;
 }
+function buildGeneralPageTarget(copy, registeredTargets, getPageUrl) {
+  return {
+    component_key: "general_page",
+    component_label: copy.generalPageTargetLabel,
+    page_url: resolvePageUrl(getPageUrl),
+    surface_ref: null,
+    metadata: {
+      capture_mode: "general_page",
+      registered_target_count: registeredTargets.length,
+      ...registeredTargets.length > 0 ? {
+        registered_targets: registeredTargets.map(
+          ({ target }) => summarizeTarget(target)
+        )
+      } : {}
+    }
+  };
+}
 function useIssueReporting() {
   const context = (0, import_react2.useContext)(IssueReportingContext);
   if (!context) {
@@ -263,6 +336,25 @@ function useIssueReporting() {
   }
   return context;
 }
+function IssueReportingPageConfig({
+  createMode
+}) {
+  const registry = (0, import_react2.useContext)(IssueReportingPageConfigRegistryContext);
+  const configId = (0, import_react2.useRef)(/* @__PURE__ */ Symbol("issue-reporting-page-config"));
+  const markerRef = (0, import_react2.useRef)(null);
+  if (!registry) {
+    throw new Error(
+      "IssueReportingPageConfig must be used within an IssueReportingProvider"
+    );
+  }
+  (0, import_react2.useEffect)(() => {
+    registry.registerPageConfig(configId.current, createMode, () => markerRef.current);
+    return () => {
+      registry.unregisterPageConfig(configId.current);
+    };
+  }, [createMode, registry]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { ref: markerRef, style: hiddenMarkerStyle });
+}
 function useIssueReportingStatus() {
   const { client, isEligible, scope } = useIssueReporting();
   return (0, import_react_query.useQuery)({
@@ -335,6 +427,7 @@ function IssueReportingProvider({
   getPageUrl,
   defaultScope,
   allowTenantScope = false,
+  defaultCreateMode = "general_page",
   copy,
   children
 }) {
@@ -352,6 +445,10 @@ function IssueReportingProvider({
   const [scope, setScope] = (0, import_react2.useState)(
     () => resolveInitialScope(defaultScope, allowTenantScope)
   );
+  const [pageConfigs, setPageConfigs] = (0, import_react2.useState)([]);
+  const [registeredTargets, setRegisteredTargets] = (0, import_react2.useState)(
+    []
+  );
   (0, import_react2.useEffect)(() => {
     setScope(resolveInitialScope(defaultScope, allowTenantScope));
   }, [allowTenantScope, defaultScope]);
@@ -361,6 +458,51 @@ function IssueReportingProvider({
   const openPopover = (0, import_react2.useCallback)(() => {
     setIsPopoverOpen(true);
   }, []);
+  const openCreateModal = (0, import_react2.useCallback)((target) => {
+    setIsPopoverOpen(false);
+    setIsReportMode(false);
+    setModalState({
+      isOpen: true,
+      mode: "create",
+      issueReportId: null,
+      issue: null,
+      target,
+      error: null,
+      isHydrating: false
+    });
+  }, []);
+  const registerPageConfig = (0, import_react2.useCallback)(
+    (id, createMode2, getElement) => {
+      setPageConfigs((current) => [
+        ...current.filter((entry) => entry.id !== id),
+        { id, createMode: createMode2, getElement }
+      ]);
+    },
+    []
+  );
+  const unregisterPageConfig = (0, import_react2.useCallback)((id) => {
+    setPageConfigs((current) => current.filter((entry) => entry.id !== id));
+  }, []);
+  const registerTarget = (0, import_react2.useCallback)(
+    (id, target, getElement) => {
+      setRegisteredTargets((current) => [
+        ...current.filter((entry) => entry.id !== id),
+        { id, target, getElement }
+      ]);
+    },
+    []
+  );
+  const unregisterTarget = (0, import_react2.useCallback)((id) => {
+    setRegisteredTargets((current) => current.filter((entry) => entry.id !== id));
+  }, []);
+  const visiblePageConfigs = pageConfigs.filter(
+    ({ getElement }) => isElementVisibleForReporting(getElement())
+  );
+  const visibleRegisteredTargets = registeredTargets.filter(
+    ({ getElement }) => isElementVisibleForReporting(getElement())
+  );
+  const createMode = visiblePageConfigs.length > 0 ? visiblePageConfigs[visiblePageConfigs.length - 1].createMode : defaultCreateMode;
+  const hasRegisteredTargets = visibleRegisteredTargets.length > 0;
   const enterReportMode = (0, import_react2.useCallback)(() => {
     setIsReportMode(true);
     setIsPopoverOpen(false);
@@ -372,6 +514,42 @@ function IssueReportingProvider({
     setModalState(initialModalState);
     setIsPopoverOpen(true);
   }, []);
+  const openPageIssueModal = (0, import_react2.useCallback)(() => {
+    if (!isEligible) {
+      return;
+    }
+    openCreateModal(
+      buildGeneralPageTarget(mergedCopy, visibleRegisteredTargets, getPageUrl)
+    );
+  }, [
+    getPageUrl,
+    isEligible,
+    mergedCopy,
+    openCreateModal,
+    visibleRegisteredTargets
+  ]);
+  const startNewIssue = (0, import_react2.useCallback)(() => {
+    if (!isEligible) {
+      return;
+    }
+    if (createMode === "surface_required") {
+      if (hasRegisteredTargets) {
+        enterReportMode();
+      }
+      return;
+    }
+    if (createMode === "surface_preferred" && hasRegisteredTargets) {
+      enterReportMode();
+      return;
+    }
+    openPageIssueModal();
+  }, [
+    createMode,
+    enterReportMode,
+    hasRegisteredTargets,
+    isEligible,
+    openPageIssueModal
+  ]);
   const hydrateIssueIntoModal = (0, import_react2.useCallback)(
     async (issueReportId, mode) => {
       setModalState({
@@ -430,18 +608,9 @@ function IssueReportingProvider({
         return;
       }
       const normalizedTarget = normalizeTarget(target, getPageUrl);
-      setIsReportMode(false);
-      setModalState({
-        isOpen: true,
-        mode: "create",
-        issueReportId: null,
-        issue: null,
-        target: normalizedTarget,
-        error: null,
-        isHydrating: false
-      });
+      openCreateModal(normalizedTarget);
     },
-    [getPageUrl, isEligible]
+    [getPageUrl, isEligible, openCreateModal]
   );
   const contextValue = (0, import_react2.useMemo)(
     () => ({
@@ -451,9 +620,12 @@ function IssueReportingProvider({
       principalId: principalId ?? null,
       copy: mergedCopy,
       isReportMode,
+      hasRegisteredTargets,
       enterReportMode,
       cancelReportMode,
       selectPanel,
+      openPageIssueModal,
+      startNewIssue,
       isPopoverOpen,
       openPopover,
       closePopover,
@@ -463,7 +635,8 @@ function IssueReportingProvider({
       retryModalHydration,
       scope,
       setScope,
-      allowTenantScope
+      allowTenantScope,
+      createMode
     }),
     [
       allowTenantScope,
@@ -471,30 +644,57 @@ function IssueReportingProvider({
       client,
       closeModal,
       closePopover,
+      createMode,
       enterReportMode,
+      hasRegisteredTargets,
       isEligible,
       isPopoverOpen,
       isReportMode,
       mergedCopy,
       modalState,
       openExistingIssueModal,
+      openPageIssueModal,
       openPopover,
       principalId,
       reporterRoleHint,
       retryModalHydration,
       scope,
-      selectPanel
+      selectPanel,
+      startNewIssue
     ]
   );
   const reportModeValue = (0, import_react2.useMemo)(
     () => ({
       isReportMode,
       selectPanel,
-      cancelReportMode
+      cancelReportMode,
+      hasRegisteredTargets,
+      registerTarget,
+      unregisterTarget
     }),
-    [cancelReportMode, isReportMode, selectPanel]
+    [
+      cancelReportMode,
+      hasRegisteredTargets,
+      isReportMode,
+      registerTarget,
+      selectPanel,
+      unregisterTarget
+    ]
+  );
+  const pageConfigRegistryValue = (0, import_react2.useMemo)(
+    () => ({
+      registerPageConfig,
+      unregisterPageConfig
+    }),
+    [registerPageConfig, unregisterPageConfig]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    IssueReportingPageConfigRegistryContext.Provider,
+    {
+      value: pageConfigRegistryValue,
+      children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ReportModeContext.Provider, { value: reportModeValue, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(IssueReportingContext.Provider, { value: contextValue, children }) })
+    }
   );
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ReportModeContext.Provider, { value: reportModeValue, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(IssueReportingContext.Provider, { value: contextValue, children }) });
 }
 
 // src/components.tsx
@@ -660,10 +860,13 @@ function IssueReportPopover({ children }) {
     openPopover,
     closePopover,
     enterReportMode,
+    openPageIssueModal,
     openExistingIssueModal,
     scope,
     setScope,
-    allowTenantScope
+    allowTenantScope,
+    createMode,
+    hasRegisteredTargets
   } = useIssueReporting();
   const history = useIssueReportingHistory("all");
   const status = useIssueReportingStatus();
@@ -677,6 +880,9 @@ function IssueReportPopover({ children }) {
     [allItems]
   );
   const statusSummary = status.data ? `${status.data.open_count} open \xB7 ${status.data.recent_resolved_count} recently resolved` : "Status reflects the active scope.";
+  const showSectionFirst = createMode === "surface_required" || createMode === "surface_preferred" && hasRegisteredTargets;
+  const sectionActionDisabled = !hasRegisteredTargets;
+  const helperText = createMode === "surface_required" ? hasRegisteredTargets ? copy.surfaceRequiredDescription : copy.specificSectionUnavailableDescription : createMode === "surface_preferred" && !hasRegisteredTargets ? copy.specificSectionUnavailableDescription : null;
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
     Popover.Root,
     {
@@ -697,19 +903,66 @@ function IssueReportPopover({ children }) {
                   /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h3", { className: "text-sm font-semibold text-slate-900", children: copy.popoverTitle }),
                   /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: "mt-1 text-xs text-slate-500", children: statusSummary })
                 ] }),
-                /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
-                  "button",
-                  {
-                    type: "button",
-                    className: "rounded-full bg-slate-900 px-3 py-2 text-xs font-semibold text-white transition hover:bg-slate-800",
-                    onClick: () => {
-                      closePopover();
-                      enterReportMode();
-                    },
-                    children: copy.reportNewAction
-                  }
-                )
+                /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "flex flex-wrap justify-end gap-2", children: showSectionFirst ? /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_jsx_runtime2.Fragment, { children: [
+                  /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+                    "button",
+                    {
+                      type: "button",
+                      className: cn(
+                        "rounded-full px-3 py-2 text-xs font-semibold transition",
+                        sectionActionDisabled ? "cursor-not-allowed bg-slate-200 text-slate-500" : "bg-slate-900 text-white hover:bg-slate-800"
+                      ),
+                      onClick: () => {
+                        if (sectionActionDisabled) {
+                          return;
+                        }
+                        closePopover();
+                        enterReportMode();
+                      },
+                      disabled: sectionActionDisabled,
+                      children: createMode === "surface_required" ? copy.reportNewAction : copy.reportSpecificAction
+                    }
+                  ),
+                  createMode !== "surface_required" ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+                    "button",
+                    {
+                      type: "button",
+                      className: "rounded-full border border-slate-200 px-3 py-2 text-xs font-semibold text-slate-700 transition hover:bg-slate-50",
+                      onClick: () => {
+                        closePopover();
+                        openPageIssueModal();
+                      },
+                      children: copy.reportPageAction
+                    }
+                  ) : null
+                ] }) : /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_jsx_runtime2.Fragment, { children: [
+                  /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+                    "button",
+                    {
+                      type: "button",
+                      className: "rounded-full bg-slate-900 px-3 py-2 text-xs font-semibold text-white transition hover:bg-slate-800",
+                      onClick: () => {
+                        closePopover();
+                        openPageIssueModal();
+                      },
+                      children: createMode === "general_page" ? copy.reportPageAction : copy.reportNewAction
+                    }
+                  ),
+                  hasRegisteredTargets ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+                    "button",
+                    {
+                      type: "button",
+                      className: "rounded-full border border-slate-200 px-3 py-2 text-xs font-semibold text-slate-700 transition hover:bg-slate-50",
+                      onClick: () => {
+                        closePopover();
+                        enterReportMode();
+                      },
+                      children: copy.reportSpecificAction
+                    }
+                  ) : null
+                ] }) })
               ] }),
+              helperText ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "rounded-2xl border border-amber-200 bg-amber-50 px-4 py-3 text-xs text-amber-900", children: helperText }) : null,
               status.error ? /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "space-y-3 rounded-2xl border border-rose-200 bg-rose-50 px-4 py-4 text-sm text-rose-700", children: [
                 /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { children: status.error.message || copy.statusLoadFailed }),
                 /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
@@ -986,9 +1239,23 @@ function ReportableSection({
 }) {
   const reportMode = useReportMode();
   const isSelectable = Boolean(reportMode?.isReportMode);
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+  const targetId = import_react4.default.useRef(/* @__PURE__ */ Symbol("reportable-section"));
+  const elementRef = import_react4.default.useRef(null);
+  (0, import_react4.useEffect)(() => {
+    if (!reportMode) {
+      return;
+    }
+    reportMode.registerTarget(targetId.current, reportableName, () => elementRef.current);
+    return () => {
+      reportMode.unregisterTarget(targetId.current);
+    };
+  }, [reportMode, reportableName]);
+  return import_react4.default.createElement(
     Component,
     {
+      ref: (node) => {
+        elementRef.current = node;
+      },
       className: cn(
         className,
         isSelectable && "cursor-pointer ring-2 ring-amber-400 transition hover:ring-amber-500"
@@ -1003,14 +1270,15 @@ function ReportableSection({
         }
       } : void 0,
       role: isSelectable ? "button" : void 0,
-      tabIndex: isSelectable ? 0 : void 0,
-      children
-    }
+      tabIndex: isSelectable ? 0 : void 0
+    },
+    children
   );
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FloatingIssueReportButton,
+  IssueReportingPageConfig,
   IssueReportingProvider,
   ReportModeContext,
   ReportableSection,

package/dist/index.mjs

@@ -9,7 +9,7 @@ import {
   X
 } from "@phosphor-icons/react";
 import { formatDistanceToNow } from "date-fns";
-import { useEffect as useEffect2, useMemo as useMemo2, useState as useState2 } from "react";
+import React2, { useEffect as useEffect2, useMemo as useMemo2, useState as useState2 } from "react";
 
 // src/provider.tsx
 import {
@@ -18,6 +18,7 @@ import {
   useContext as useContext2,
   useEffect,
   useMemo,
+  useRef,
   useState
 } from "react";
 import {
@@ -52,10 +53,24 @@ var initialModalState = {
 var IssueReportingContext = createContext2(
   void 0
 );
+var IssueReportingPageConfigRegistryContext = createContext2(void 0);
+var hiddenMarkerStyle = {
+  position: "absolute",
+  width: "1px",
+  height: "1px",
+  padding: 0,
+  margin: "-1px",
+  overflow: "hidden",
+  clip: "rect(0, 0, 0, 0)",
+  whiteSpace: "nowrap",
+  border: 0
+};
 var defaultIssueReportingCopy = {
   entryAriaLabel: "Report issue",
   popoverTitle: "Issue Reports",
   reportNewAction: "Report New Issue",
+  reportPageAction: "Report This Page",
+  reportSpecificAction: "Pick Specific Section",
   filtersAll: "All",
   filtersUnresolved: "Unresolved",
   filtersResolved: "Resolved",
@@ -72,6 +87,9 @@ var defaultIssueReportingCopy = {
   reportModeTitle: "Report mode is active",
   reportModeDescription: "Click a highlighted section to capture the broken surface.",
   reportModeCancelAction: "Cancel",
+  generalPageTargetLabel: "Current Page",
+  surfaceRequiredDescription: "This page requires selecting a specific section before you submit a report.",
+  specificSectionUnavailableDescription: "No specific sections are registered on this page right now.",
   createTitlePrefix: "Report Issue",
   editTitlePrefix: "Edit Issue",
   replyTitlePrefix: "Reply to",
@@ -136,6 +154,44 @@ function normalizeTarget(target, getPageUrl) {
     metadata: target.metadata ?? {}
   };
 }
+function summarizeTarget(target) {
+  if (typeof target === "string") {
+    const normalized = target.trim();
+    return {
+      component_key: normalized,
+      component_label: normalized,
+      surface_ref: null,
+      metadata: {}
+    };
+  }
+  const key = target.componentKey.trim();
+  return {
+    component_key: key,
+    component_label: (target.componentLabel ?? key).trim(),
+    surface_ref: target.surfaceRef ?? null,
+    metadata: target.metadata ?? {}
+  };
+}
+function isElementVisibleForReporting(element) {
+  if (!element || typeof window === "undefined") {
+    return true;
+  }
+  let current = element;
+  while (current) {
+    if (current.getAttribute("aria-hidden") === "true") {
+      return false;
+    }
+    if (current instanceof HTMLElement && (current.hidden || current.inert)) {
+      return false;
+    }
+    const computedStyle = window.getComputedStyle(current);
+    if (computedStyle.display === "none" || computedStyle.visibility === "hidden" || computedStyle.visibility === "collapse") {
+      return false;
+    }
+    current = current.parentElement;
+  }
+  return true;
+}
 function normalizeIssueTarget(issue) {
   return {
     component_key: issue.target.component_key,
@@ -217,6 +273,23 @@ function getIssueNoteLengthMessage(note, copy) {
   }
   return `${note.length}/${NOTE_MAX_LENGTH}`;
 }
+function buildGeneralPageTarget(copy, registeredTargets, getPageUrl) {
+  return {
+    component_key: "general_page",
+    component_label: copy.generalPageTargetLabel,
+    page_url: resolvePageUrl(getPageUrl),
+    surface_ref: null,
+    metadata: {
+      capture_mode: "general_page",
+      registered_target_count: registeredTargets.length,
+      ...registeredTargets.length > 0 ? {
+        registered_targets: registeredTargets.map(
+          ({ target }) => summarizeTarget(target)
+        )
+      } : {}
+    }
+  };
+}
 function useIssueReporting() {
   const context = useContext2(IssueReportingContext);
   if (!context) {
@@ -226,6 +299,25 @@ function useIssueReporting() {
   }
   return context;
 }
+function IssueReportingPageConfig({
+  createMode
+}) {
+  const registry = useContext2(IssueReportingPageConfigRegistryContext);
+  const configId = useRef(/* @__PURE__ */ Symbol("issue-reporting-page-config"));
+  const markerRef = useRef(null);
+  if (!registry) {
+    throw new Error(
+      "IssueReportingPageConfig must be used within an IssueReportingProvider"
+    );
+  }
+  useEffect(() => {
+    registry.registerPageConfig(configId.current, createMode, () => markerRef.current);
+    return () => {
+      registry.unregisterPageConfig(configId.current);
+    };
+  }, [createMode, registry]);
+  return /* @__PURE__ */ jsx("span", { ref: markerRef, style: hiddenMarkerStyle });
+}
 function useIssueReportingStatus() {
   const { client, isEligible, scope } = useIssueReporting();
   return useQuery({
@@ -298,6 +390,7 @@ function IssueReportingProvider({
   getPageUrl,
   defaultScope,
   allowTenantScope = false,
+  defaultCreateMode = "general_page",
   copy,
   children
 }) {
@@ -315,6 +408,10 @@ function IssueReportingProvider({
   const [scope, setScope] = useState(
     () => resolveInitialScope(defaultScope, allowTenantScope)
   );
+  const [pageConfigs, setPageConfigs] = useState([]);
+  const [registeredTargets, setRegisteredTargets] = useState(
+    []
+  );
   useEffect(() => {
     setScope(resolveInitialScope(defaultScope, allowTenantScope));
   }, [allowTenantScope, defaultScope]);
@@ -324,6 +421,51 @@ function IssueReportingProvider({
   const openPopover = useCallback(() => {
     setIsPopoverOpen(true);
   }, []);
+  const openCreateModal = useCallback((target) => {
+    setIsPopoverOpen(false);
+    setIsReportMode(false);
+    setModalState({
+      isOpen: true,
+      mode: "create",
+      issueReportId: null,
+      issue: null,
+      target,
+      error: null,
+      isHydrating: false
+    });
+  }, []);
+  const registerPageConfig = useCallback(
+    (id, createMode2, getElement) => {
+      setPageConfigs((current) => [
+        ...current.filter((entry) => entry.id !== id),
+        { id, createMode: createMode2, getElement }
+      ]);
+    },
+    []
+  );
+  const unregisterPageConfig = useCallback((id) => {
+    setPageConfigs((current) => current.filter((entry) => entry.id !== id));
+  }, []);
+  const registerTarget = useCallback(
+    (id, target, getElement) => {
+      setRegisteredTargets((current) => [
+        ...current.filter((entry) => entry.id !== id),
+        { id, target, getElement }
+      ]);
+    },
+    []
+  );
+  const unregisterTarget = useCallback((id) => {
+    setRegisteredTargets((current) => current.filter((entry) => entry.id !== id));
+  }, []);
+  const visiblePageConfigs = pageConfigs.filter(
+    ({ getElement }) => isElementVisibleForReporting(getElement())
+  );
+  const visibleRegisteredTargets = registeredTargets.filter(
+    ({ getElement }) => isElementVisibleForReporting(getElement())
+  );
+  const createMode = visiblePageConfigs.length > 0 ? visiblePageConfigs[visiblePageConfigs.length - 1].createMode : defaultCreateMode;
+  const hasRegisteredTargets = visibleRegisteredTargets.length > 0;
   const enterReportMode = useCallback(() => {
     setIsReportMode(true);
     setIsPopoverOpen(false);
@@ -335,6 +477,42 @@ function IssueReportingProvider({
     setModalState(initialModalState);
     setIsPopoverOpen(true);
   }, []);
+  const openPageIssueModal = useCallback(() => {
+    if (!isEligible) {
+      return;
+    }
+    openCreateModal(
+      buildGeneralPageTarget(mergedCopy, visibleRegisteredTargets, getPageUrl)
+    );
+  }, [
+    getPageUrl,
+    isEligible,
+    mergedCopy,
+    openCreateModal,
+    visibleRegisteredTargets
+  ]);
+  const startNewIssue = useCallback(() => {
+    if (!isEligible) {
+      return;
+    }
+    if (createMode === "surface_required") {
+      if (hasRegisteredTargets) {
+        enterReportMode();
+      }
+      return;
+    }
+    if (createMode === "surface_preferred" && hasRegisteredTargets) {
+      enterReportMode();
+      return;
+    }
+    openPageIssueModal();
+  }, [
+    createMode,
+    enterReportMode,
+    hasRegisteredTargets,
+    isEligible,
+    openPageIssueModal
+  ]);
   const hydrateIssueIntoModal = useCallback(
     async (issueReportId, mode) => {
       setModalState({
@@ -393,18 +571,9 @@ function IssueReportingProvider({
         return;
       }
       const normalizedTarget = normalizeTarget(target, getPageUrl);
-      setIsReportMode(false);
-      setModalState({
-        isOpen: true,
-        mode: "create",
-        issueReportId: null,
-        issue: null,
-        target: normalizedTarget,
-        error: null,
-        isHydrating: false
-      });
+      openCreateModal(normalizedTarget);
     },
-    [getPageUrl, isEligible]
+    [getPageUrl, isEligible, openCreateModal]
   );
   const contextValue = useMemo(
     () => ({
@@ -414,9 +583,12 @@ function IssueReportingProvider({
       principalId: principalId ?? null,
       copy: mergedCopy,
       isReportMode,
+      hasRegisteredTargets,
       enterReportMode,
       cancelReportMode,
       selectPanel,
+      openPageIssueModal,
+      startNewIssue,
       isPopoverOpen,
       openPopover,
       closePopover,
@@ -426,7 +598,8 @@ function IssueReportingProvider({
       retryModalHydration,
       scope,
       setScope,
-      allowTenantScope
+      allowTenantScope,
+      createMode
     }),
     [
       allowTenantScope,
@@ -434,30 +607,57 @@ function IssueReportingProvider({
       client,
       closeModal,
       closePopover,
+      createMode,
       enterReportMode,
+      hasRegisteredTargets,
       isEligible,
       isPopoverOpen,
       isReportMode,
       mergedCopy,
       modalState,
       openExistingIssueModal,
+      openPageIssueModal,
       openPopover,
       principalId,
       reporterRoleHint,
       retryModalHydration,
       scope,
-      selectPanel
+      selectPanel,
+      startNewIssue
     ]
   );
   const reportModeValue = useMemo(
     () => ({
       isReportMode,
       selectPanel,
-      cancelReportMode
+      cancelReportMode,
+      hasRegisteredTargets,
+      registerTarget,
+      unregisterTarget
     }),
-    [cancelReportMode, isReportMode, selectPanel]
+    [
+      cancelReportMode,
+      hasRegisteredTargets,
+      isReportMode,
+      registerTarget,
+      selectPanel,
+      unregisterTarget
+    ]
+  );
+  const pageConfigRegistryValue = useMemo(
+    () => ({
+      registerPageConfig,
+      unregisterPageConfig
+    }),
+    [registerPageConfig, unregisterPageConfig]
+  );
+  return /* @__PURE__ */ jsx(
+    IssueReportingPageConfigRegistryContext.Provider,
+    {
+      value: pageConfigRegistryValue,
+      children: /* @__PURE__ */ jsx(ReportModeContext.Provider, { value: reportModeValue, children: /* @__PURE__ */ jsx(IssueReportingContext.Provider, { value: contextValue, children }) })
+    }
   );
-  return /* @__PURE__ */ jsx(ReportModeContext.Provider, { value: reportModeValue, children: /* @__PURE__ */ jsx(IssueReportingContext.Provider, { value: contextValue, children }) });
 }
 
 // src/components.tsx
@@ -623,10 +823,13 @@ function IssueReportPopover({ children }) {
     openPopover,
     closePopover,
     enterReportMode,
+    openPageIssueModal,
     openExistingIssueModal,
     scope,
     setScope,
-    allowTenantScope
+    allowTenantScope,
+    createMode,
+    hasRegisteredTargets
   } = useIssueReporting();
   const history = useIssueReportingHistory("all");
   const status = useIssueReportingStatus();
@@ -640,6 +843,9 @@ function IssueReportPopover({ children }) {
     [allItems]
   );
   const statusSummary = status.data ? `${status.data.open_count} open \xB7 ${status.data.recent_resolved_count} recently resolved` : "Status reflects the active scope.";
+  const showSectionFirst = createMode === "surface_required" || createMode === "surface_preferred" && hasRegisteredTargets;
+  const sectionActionDisabled = !hasRegisteredTargets;
+  const helperText = createMode === "surface_required" ? hasRegisteredTargets ? copy.surfaceRequiredDescription : copy.specificSectionUnavailableDescription : createMode === "surface_preferred" && !hasRegisteredTargets ? copy.specificSectionUnavailableDescription : null;
   return /* @__PURE__ */ jsxs(
     Popover.Root,
     {
@@ -660,19 +866,66 @@ function IssueReportPopover({ children }) {
                   /* @__PURE__ */ jsx2("h3", { className: "text-sm font-semibold text-slate-900", children: copy.popoverTitle }),
                   /* @__PURE__ */ jsx2("p", { className: "mt-1 text-xs text-slate-500", children: statusSummary })
                 ] }),
-                /* @__PURE__ */ jsx2(
-                  "button",
-                  {
-                    type: "button",
-                    className: "rounded-full bg-slate-900 px-3 py-2 text-xs font-semibold text-white transition hover:bg-slate-800",
-                    onClick: () => {
-                      closePopover();
-                      enterReportMode();
-                    },
-                    children: copy.reportNewAction
-                  }
-                )
+                /* @__PURE__ */ jsx2("div", { className: "flex flex-wrap justify-end gap-2", children: showSectionFirst ? /* @__PURE__ */ jsxs(Fragment, { children: [
+                  /* @__PURE__ */ jsx2(
+                    "button",
+                    {
+                      type: "button",
+                      className: cn(
+                        "rounded-full px-3 py-2 text-xs font-semibold transition",
+                        sectionActionDisabled ? "cursor-not-allowed bg-slate-200 text-slate-500" : "bg-slate-900 text-white hover:bg-slate-800"
+                      ),
+                      onClick: () => {
+                        if (sectionActionDisabled) {
+                          return;
+                        }
+                        closePopover();
+                        enterReportMode();
+                      },
+                      disabled: sectionActionDisabled,
+                      children: createMode === "surface_required" ? copy.reportNewAction : copy.reportSpecificAction
+                    }
+                  ),
+                  createMode !== "surface_required" ? /* @__PURE__ */ jsx2(
+                    "button",
+                    {
+                      type: "button",
+                      className: "rounded-full border border-slate-200 px-3 py-2 text-xs font-semibold text-slate-700 transition hover:bg-slate-50",
+                      onClick: () => {
+                        closePopover();
+                        openPageIssueModal();
+                      },
+                      children: copy.reportPageAction
+                    }
+                  ) : null
+                ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+                  /* @__PURE__ */ jsx2(
+                    "button",
+                    {
+                      type: "button",
+                      className: "rounded-full bg-slate-900 px-3 py-2 text-xs font-semibold text-white transition hover:bg-slate-800",
+                      onClick: () => {
+                        closePopover();
+                        openPageIssueModal();
+                      },
+                      children: createMode === "general_page" ? copy.reportPageAction : copy.reportNewAction
+                    }
+                  ),
+                  hasRegisteredTargets ? /* @__PURE__ */ jsx2(
+                    "button",
+                    {
+                      type: "button",
+                      className: "rounded-full border border-slate-200 px-3 py-2 text-xs font-semibold text-slate-700 transition hover:bg-slate-50",
+                      onClick: () => {
+                        closePopover();
+                        enterReportMode();
+                      },
+                      children: copy.reportSpecificAction
+                    }
+                  ) : null
+                ] }) })
               ] }),
+              helperText ? /* @__PURE__ */ jsx2("div", { className: "rounded-2xl border border-amber-200 bg-amber-50 px-4 py-3 text-xs text-amber-900", children: helperText }) : null,
               status.error ? /* @__PURE__ */ jsxs("div", { className: "space-y-3 rounded-2xl border border-rose-200 bg-rose-50 px-4 py-4 text-sm text-rose-700", children: [
                 /* @__PURE__ */ jsx2("div", { children: status.error.message || copy.statusLoadFailed }),
                 /* @__PURE__ */ jsx2(
@@ -949,9 +1202,23 @@ function ReportableSection({
 }) {
   const reportMode = useReportMode();
   const isSelectable = Boolean(reportMode?.isReportMode);
-  return /* @__PURE__ */ jsx2(
+  const targetId = React2.useRef(/* @__PURE__ */ Symbol("reportable-section"));
+  const elementRef = React2.useRef(null);
+  useEffect2(() => {
+    if (!reportMode) {
+      return;
+    }
+    reportMode.registerTarget(targetId.current, reportableName, () => elementRef.current);
+    return () => {
+      reportMode.unregisterTarget(targetId.current);
+    };
+  }, [reportMode, reportableName]);
+  return React2.createElement(
     Component,
     {
+      ref: (node) => {
+        elementRef.current = node;
+      },
       className: cn(
         className,
         isSelectable && "cursor-pointer ring-2 ring-amber-400 transition hover:ring-amber-500"
@@ -966,13 +1233,14 @@ function ReportableSection({
         }
       } : void 0,
       role: isSelectable ? "button" : void 0,
-      tabIndex: isSelectable ? 0 : void 0,
-      children
-    }
+      tabIndex: isSelectable ? 0 : void 0
+    },
+    children
   );
 }
 export {
   FloatingIssueReportButton,
+  IssueReportingPageConfig,
   IssueReportingProvider,
   ReportModeContext,
   ReportableSection,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps-issue-reporting-react",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Shared React issue-reporting UI for Sweet Potato platform consumers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,7 +24,7 @@
     "support"
   ],
   "author": "buildooor",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/build000r/sweet-potato"
@@ -38,7 +38,7 @@
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-popover": "^1.1.15",
     "date-fns": "^4.1.0",
-    "spaps-types": "^1.1.1"
+    "spaps-types": "^1.1.2"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",
@@ -72,4 +72,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}