@stigmer/react 3.2.2 → 3.3.0

package/src/iam-policy/useCheckPermission.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import {
   CheckMyPermissionInputSchema,
@@ -18,6 +18,25 @@ export interface PermissionCheckResource {
   readonly id: string;
 }
 
+/** Options for {@link useCheckPermission}. */
+export interface CheckPermissionOptions {
+  /**
+   * Behavior when authorization cannot be confirmed — the check is in
+   * flight, the RPC failed, the resource is `null`, or the server does
+   * not implement authorization checks (OSS edition).
+   *
+   * - `"open"` (default): `allowed` is `true`. Right for gating
+   *   *capabilities* (buttons, actions) — the server re-checks every
+   *   request anyway, and all UI stays visible in single-user local
+   *   mode.
+   * - `"closed"`: `allowed` is `false` until the server explicitly
+   *   authorizes. Right for *discoverability* surfaces (navigation to
+   *   operator-only areas) that must not appear on deployments where
+   *   the feature does not exist.
+   */
+  readonly fail?: "open" | "closed";
+}
+
 /** Return value of {@link useCheckPermission}. */
 export interface UseCheckPermissionReturn {
   /** Whether the current user has the specified permission. */
@@ -34,21 +53,24 @@ export interface UseCheckPermissionReturn {
  *
  * Wraps `iamPolicy.checkMyPermission()` — the dedicated self-check RPC
  * where the server derives the principal from the authenticated token
- * (the client never names a principal) — with caching and graceful
- * degradation. When the server does not support authorization checks
- * (OSS edition where the IAM service is not registered), the hook
- * returns `allowed: true` — ensuring all UI is visible in single-user
- * local mode.
+ * (the client never names a principal) — with caching and configurable
+ * degradation. By default the hook *fails open*: when the server does
+ * not support authorization checks (OSS edition where the IAM service
+ * is not registered), it returns `allowed: true` so all UI remains
+ * visible in single-user local mode. Pass `{ fail: "closed" }` for
+ * surfaces that must stay hidden until authorization is confirmed
+ * (see {@link CheckPermissionOptions}).
  *
- * Pass `null` as `resource` to skip the check (returns `allowed: true`
- * immediately — the "no resource yet" case is permissive to avoid
- * flashing hidden UI).
+ * Pass `null` as `resource` to skip the check — the result resolves
+ * through the fail mode (`allowed: true` under the default fail-open).
  *
- * Results are cached per (kind, id, relation) triple for the lifetime
- * of the component mount. Re-mount or change inputs to re-check.
+ * Only genuine server verdicts are cached (per (kind, id, relation)
+ * triple, for the lifetime of the component mount). A failed check is
+ * never cached, so a transient error does not pin a wrong answer.
  *
  * @param resource  - The resource to check, or `null` to skip.
  * @param relation  - The permission to check (e.g. "can_edit", "can_grant_access").
+ * @param options   - Fail-mode configuration; see {@link CheckPermissionOptions}.
  *
  * @example
  * ```tsx
@@ -63,9 +85,13 @@ export interface UseCheckPermissionReturn {
 export function useCheckPermission(
   resource: PermissionCheckResource | null,
   relation: string,
+  options?: CheckPermissionOptions,
 ): UseCheckPermissionReturn {
   const stigmer = useStigmer();
-  const [allowed, setAllowed] = useState(true);
+  const failMode = options?.fail ?? "open";
+  const failValue = failMode === "open";
+
+  const [allowed, setAllowed] = useState(failValue);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -74,7 +100,7 @@ export function useCheckPermission(
 
   useEffect(() => {
     if (!resource || !cacheKey) {
-      setAllowed(true);
+      setAllowed(failValue);
       setIsLoading(false);
       return;
     }
@@ -87,6 +113,7 @@ export function useCheckPermission(
     }
 
     let cancelled = false;
+    setAllowed(failValue);
     setIsLoading(true);
 
     const input = create(CheckMyPermissionInputSchema, {
@@ -108,11 +135,10 @@ export function useCheckPermission(
       })
       .catch((err: unknown) => {
         if (cancelled) return;
-        // Graceful degradation: if the IAM service is unavailable
-        // (OSS edition), default to permissive. This ensures all
-        // UI remains visible in single-user local mode.
-        cacheRef.current.set(cacheKey, true);
-        setAllowed(true);
+        // Degradation is fail-mode-resolved and deliberately NOT cached:
+        // an error is not an authorization verdict, and caching it would
+        // pin a possibly-wrong answer for the mount's lifetime.
+        setAllowed(failValue);
         setError(err instanceof Error ? err : new Error(String(err)));
       })
       .finally(() => {
@@ -122,7 +148,7 @@ export function useCheckPermission(
     return () => {
       cancelled = true;
     };
-  }, [cacheKey, resource?.kind, resource?.id, relation, stigmer]);
+  }, [cacheKey, resource?.kind, resource?.id, relation, failValue, stigmer]);
 
   return { allowed, isLoading, error };
 }

package/src/index.ts

@@ -346,9 +346,6 @@ export {
   toFileDiffEntry,
   FILE_CHANGE_DOCUMENT_ENTRY_ID,
   fileChangeTabPath,
-  AGENT_EXECUTION_DOCUMENT_ENTRY_ID,
-  agentExecutionTabPath,
-  parseAgentExecutionTabPath,
   EmptyChangeNotice,
   isTextArtifact,
   formatArtifactSize,
@@ -363,6 +360,7 @@ export type {
   SharedAgentExecutionFields,
   UseCreateAgentExecutionReturn,
   UseExecutionStreamReturn,
+  UseLiveAgentExecutionOptions,
   UseLiveAgentExecutionReturn,
   UseAgentExecutionActionsOptions,
   UseAgentExecutionActionsReturn,
@@ -679,6 +677,88 @@ export type {
   AgentWizardData,
 } from "./agent/index.js";
 
+// Datastore — data hooks (kind family + describe projection), record
+// hooks (find/insert/update/delete + grid collection), guarded delete,
+// the canonical value semantics of declared fields, the typed filter
+// model, and the six styled components (detail view, records browser,
+// filter builder, record form, schema view, sync report, delete dialog)
+export {
+  useDatastore,
+  useDatastoreList,
+  useDatastoreCount,
+  useDatastoreSearch,
+  useDatastoreDescription,
+  DEFAULT_PARTITION,
+  useRecordList,
+  useInsertRecord,
+  useUpdateRecord,
+  useDeleteRecord,
+  useRecordCollection,
+  useDeleteDatastore,
+  buildUpdateFields,
+  coerceFieldValue,
+  formatFieldValue,
+  formatSystemTimestamp,
+  isListOperator,
+  isSortableField,
+  isValuelessOperator,
+  operatorsForField,
+  OPERATOR_LABELS,
+  RESERVED_FIELD_NAMES,
+  SYSTEM_FIELD_OPERATORS,
+  buildRecordFilter,
+  filterableFields,
+  formatConditionChip,
+  isConditionComplete,
+  FieldValueControl,
+  FIELD_INPUT_CLASSES,
+  CollectionSchemaView,
+  formatSubject,
+  DatastoreSyncReport,
+  RecordFilterBuilder,
+  RecordFormPanel,
+  CollectionRecordsBrowser,
+  DeleteDatastoreDialog,
+  DatastoreDetailView,
+  DatastoreIcon,
+} from "./datastore/index.js";
+export type {
+  UseDatastoreReturn,
+  UseDatastoreListOptions,
+  UseDatastoreListReturn,
+  UseDatastoreCountOptions,
+  UseDatastoreCountReturn,
+  UseDatastoreSearchOptions,
+  UseDatastoreSearchReturn,
+  UseDatastoreDescriptionReturn,
+  RecordScope,
+  UseRecordListParams,
+  UseRecordListReturn,
+  InsertRecordArgs,
+  UseInsertRecordReturn,
+  UpdateRecordArgs,
+  UseUpdateRecordReturn,
+  DeleteRecordArgs,
+  UseDeleteRecordReturn,
+  RecordColumnDef,
+  UseRecordCollectionOptions,
+  UseRecordCollectionReturn,
+  DeleteDatastoreArgs,
+  UseDeleteDatastoreReturn,
+  CoerceResult,
+  FilterableField,
+  RecordConditionDraft,
+  FieldValueControlProps,
+  CollectionSchemaViewProps,
+  DatastoreSyncReportProps,
+  RecordFilterBuilderProps,
+  RecordFormPanelProps,
+  CollectionRecordsBrowserProps,
+  DeleteDatastoreDialogProps,
+  DatastoreDetailTab,
+  DatastoreDetailViewProps,
+} from "./datastore/index.js";
+
 // Environment — data hooks, list hook, personal convenience hook, secret reveal, variable management, env var form, system env vars, and styled components
 export {
   useEnvironment,
@@ -772,6 +852,7 @@ export type {
   UseShareFlowReturn,
   ShareFlowResource,
   UseCheckPermissionReturn,
+  CheckPermissionOptions,
   PermissionCheckResource,
   RoleSelectorProps,
   PrincipalPickerProps,
@@ -834,9 +915,15 @@ export {
   useCreditLedger,
   useBillingUsageReport,
   useCustomerModelPricing,
+  usePricingGovernance,
+  useModelPricingBaselines,
+  useModelGovernanceView,
   useCreateCheckoutSession,
   useCreateBillingPortalSession,
   useSetAutoRechargeConfig,
+  useDecidePricingOverride,
+  useUpsertModelPricingBaseline,
+  useRetireModelPricingBaseline,
   BillingSection,
   CreditBalanceCard,
   PaymentMethodCard,
@@ -844,6 +931,9 @@ export {
   CreditPackGrid,
   CreditLedgerTable,
   LowBalanceBanner,
+  PricingGovernancePanel,
+  ModelCatalogPanel,
+  PricingGovernanceConsole,
   CREDIT_PACKS,
   formatPackPrice,
   formatCreditCount,
@@ -860,11 +950,23 @@ export type {
   UseCreditLedgerOptions,
   UseBillingUsageReportReturn,
   UseCustomerModelPricingReturn,
+  UsePricingGovernanceReturn,
+  UseModelPricingBaselinesOptions,
+  UseModelPricingBaselinesReturn,
+  GovernanceFlow,
+  ModelGovernanceRow,
+  UseModelGovernanceViewReturn,
   CreateCheckoutSessionInput,
   UseCreateCheckoutSessionReturn,
   UseCreateBillingPortalSessionReturn,
   SetAutoRechargeConfigInput,
   UseSetAutoRechargeConfigReturn,
+  DecidePricingOverrideInput,
+  UseDecidePricingOverrideReturn,
+  UpsertModelPricingBaselineInput,
+  UseUpsertModelPricingBaselineReturn,
+  RetireModelPricingBaselineInput,
+  UseRetireModelPricingBaselineReturn,
   BillingSectionProps,
   CreditBalanceCardProps,
   PaymentMethodCardProps,
@@ -872,11 +974,46 @@ export type {
   CreditPackGridProps,
   CreditLedgerTableProps,
   LowBalanceBannerProps,
+  PricingGovernancePanelProps,
+  ModelCatalogPanelProps,
+  PricingGovernanceConsoleProps,
+  PricingGovernanceTab,
   CreditPackInfo,
 } from "./billing/index.js";
 
+// Cursor accounts — platform-operator management of managed Cursor teams
+// (admin keys, member execution keys, org assignments, roster/spend)
+export {
+  useCursorAccounts,
+  useCursorAccountView,
+  useUpsertCursorAccount,
+  useDeleteCursorAccount,
+  useCursorMemberKeyActions,
+  useSyncCursorAccount,
+  CursorAccountsConsole,
+  CursorAccountEditor,
+  CursorAccountsAccessNotice,
+} from "./cursor-accounts/index.js";
+export type {
+  UseCursorAccountsReturn,
+  UseCursorAccountViewReturn,
+  UseUpsertCursorAccountReturn,
+  DeleteCursorAccountInput,
+  UseDeleteCursorAccountReturn,
+  AddCursorMemberKeyInput,
+  RemoveCursorMemberKeyInput,
+  UseCursorMemberKeyActionsReturn,
+  UseSyncCursorAccountReturn,
+  CursorAccountsConsoleProps,
+  CursorAccountEditorProps,
+} from "./cursor-accounts/index.js";
+
 // Settings — navigation structure + section components shared across app shells
-export { SETTINGS_NAV_GROUPS } from "./settings/index.js";
+export {
+  SETTINGS_NAV_GROUPS,
+  PLATFORM_SETTINGS_NAV_GROUP,
+  useSettingsNavGroups,
+} from "./settings/index.js";
 export type { SettingsNavItem, SettingsNavGroup } from "./settings/index.js";
 export { ApiKeysSection } from "./settings/index.js";
 export { MembersSection } from "./settings/index.js";
@@ -1140,15 +1277,8 @@ export {
   findStreamingPlan,
   PLAN_ARTIFACT_NAME,
   PLAN_ARTIFACT_SUFFIX,
-  parseResourceYaml,
-  serializeAgentYaml,
-  serializeMcpServerYaml,
-  serializeAgentInputYaml,
-  serializeMcpServerInputYaml,
   useApplyResource,
   useExportResource,
-  useImportResource,
-  ImportResourceDialog,
   VisibilitySelector,
   VisibilityBadge,
   blueprintVisibilityLevels,
@@ -1165,23 +1295,42 @@ export type {
   SessionPlan,
   StreamingPlan,
   UseDetectSkillPackageReturn,
-  ParsedResource,
   UseApplyResourceReturn,
   ApplyResourceResult,
   PushSkillParams,
   UseExportResourceOptions,
   UseExportResourceReturn,
-  ImportFormat,
-  ImportPreview,
-  UseImportResourceReturn,
-  ImportResourceDialogProps,
   VisibilitySelectorProps,
+  VisibilityBadgeProps,
   VisibilityLevelOption,
   BlueprintVisibilityLevelsContext,
   VisibilityResourceKind,
   UseUpdateVisibilityReturn,
 } from "./library/index.js";
 
+// Manifest — kind-agnostic YAML edit/apply (editor, hooks, dialogs)
+export {
+  YamlEditor,
+  useEditResourceYaml,
+  useApplyManifest,
+  EditResourceYamlDialog,
+  ApplyManifestDialog,
+  RedactedSecretsNotice,
+} from "./manifest/index.js";
+export type {
+  YamlEditorProps,
+  EditYamlTarget,
+  EditYamlValidation,
+  UseEditResourceYamlOptions,
+  UseEditResourceYamlReturn,
+  ManifestEntryStatus,
+  ManifestPreviewEntry,
+  UseApplyManifestReturn,
+  EditResourceYamlDialogProps,
+  ApplyManifestDialogProps,
+  RedactedSecretsNoticeProps,
+} from "./manifest/index.js";
+
 // Action menu — compound component for resource item actions
 export { ActionMenu } from "./action-menu/index.js";
 export type {
@@ -1485,7 +1634,7 @@ export {
   WorkflowChangesTab,
   WorkflowUsageTab,
   WorkflowArtifactDocument,
-  WorkflowAgentExecutionDocument,
+  WorkflowAgentCallTranscript,
   useWorkflowArtifactDownload,
   useWorkflowExecutionFileChanges,
   enumerateAgentCallChildren,
@@ -1627,7 +1776,7 @@ export type {
   UseWorkflowExecutionFileChangesOptions,
   UseWorkflowExecutionFileChangesReturn,
   WorkflowArtifactDocumentProps,
-  WorkflowAgentExecutionDocumentProps,
+  WorkflowAgentCallTranscriptProps,
   WorkflowAgentExecutionHitl,
   UseWorkflowArtifactDownloadReturn,
   WorkflowArtifactEntry,

package/src/internal/__tests__/useInViewport.test.tsx

@@ -0,0 +1,115 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, act, screen, cleanup } from "@testing-library/react";
+import React from "react";
+import { useInViewport, type UseInViewportReturn } from "../useInViewport";
+
+// ---------------------------------------------------------------------------
+// Test harness — renders a real element so the ref gets populated
+// ---------------------------------------------------------------------------
+
+let latestResult: UseInViewportReturn;
+
+function Harness() {
+  const result = useInViewport();
+  latestResult = result;
+  return <div ref={result.ref} data-testid="target" />;
+}
+
+// ---------------------------------------------------------------------------
+// Observer mock (the useAutoScroll.test pattern)
+// ---------------------------------------------------------------------------
+
+type IOCallback = IntersectionObserverCallback;
+
+let ioCallback: IOCallback;
+let ioDisconnect: ReturnType<typeof vi.fn>;
+let ioObserve: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  ioDisconnect = vi.fn();
+  ioObserve = vi.fn();
+
+  vi.stubGlobal(
+    "IntersectionObserver",
+    vi.fn((cb: IOCallback) => {
+      ioCallback = cb;
+      return {
+        observe: ioObserve,
+        unobserve: vi.fn(),
+        disconnect: ioDisconnect,
+        takeRecords: vi.fn(() => []),
+        root: null,
+        rootMargin: "",
+        thresholds: [0],
+      };
+    }),
+  );
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function fireIO(isIntersecting: boolean) {
+  act(() => {
+    ioCallback(
+      [{ isIntersecting } as IntersectionObserverEntry],
+      {} as IntersectionObserver,
+    );
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("useInViewport", () => {
+  it("starts not-visible until the observer's first callback", () => {
+    render(<Harness />);
+    expect(latestResult.isVisible).toBe(false);
+  });
+
+  it("observes the target element on mount", () => {
+    render(<Harness />);
+    expect(ioObserve).toHaveBeenCalledWith(screen.getByTestId("target"));
+  });
+
+  it("uses the top-level viewport as root with the pre-warm margin", () => {
+    render(<Harness />);
+    const IOConstructor = vi.mocked(IntersectionObserver);
+    const options = IOConstructor.mock.calls[0]?.[1];
+    expect(options?.root).toBeNull();
+    expect(options?.rootMargin).toBe("200px 0px 200px 0px");
+  });
+
+  it("flips visible on enter and back on leave", () => {
+    render(<Harness />);
+
+    fireIO(true);
+    expect(latestResult.isVisible).toBe(true);
+
+    fireIO(false);
+    expect(latestResult.isVisible).toBe(false);
+  });
+
+  it("reads the LATEST entry when a batch carries several", () => {
+    render(<Harness />);
+    act(() => {
+      ioCallback(
+        [
+          { isIntersecting: true } as IntersectionObserverEntry,
+          { isIntersecting: false } as IntersectionObserverEntry,
+        ],
+        {} as IntersectionObserver,
+      );
+    });
+    expect(latestResult.isVisible).toBe(false);
+  });
+
+  it("disconnects the observer on unmount", () => {
+    const { unmount } = render(<Harness />);
+    unmount();
+    expect(ioDisconnect).toHaveBeenCalled();
+  });
+});

package/src/internal/useInViewport.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * Pre-warm margin in pixels. The element is reported visible while it is
+ * within this distance of the viewport, so consumers that attach expensive
+ * resources on visibility (e.g. a live stream subscription) connect just
+ * BEFORE the element scrolls into view and linger just after it leaves —
+ * a fast scroll past a row never thrashes connect/disconnect.
+ */
+const PREWARM_MARGIN_PX = 200;
+
+export interface UseInViewportReturn {
+  /** Attach to the element whose viewport visibility is tracked. */
+  readonly ref: React.RefObject<HTMLDivElement | null>;
+  /** True while the element is within the pre-warmed viewport. */
+  readonly isVisible: boolean;
+}
+
+/**
+ * Headless viewport-visibility hook over `IntersectionObserver`.
+ *
+ * `root` is deliberately `null` (the top-level viewport): per the
+ * IntersectionObserver spec, an element clipped by any intervening
+ * scroll container (e.g. the workflow thread's own scroller) does not
+ * intersect the viewport either, so nested scroll contexts are handled
+ * without naming them. `display: none` subtrees report not-visible — a
+ * CSS-hidden center view correctly suspends its visibility-gated work.
+ *
+ * Starts `false` until the observer's first callback; consumers should
+ * treat visibility as an upgrade signal, not a render gate.
+ *
+ * @internal Not part of the public API (promote if a second consumer
+ * appears outside the workflow thread).
+ */
+export function useInViewport(): UseInViewportReturn {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    const io = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[entries.length - 1];
+        if (!entry) return;
+        setIsVisible(entry.isIntersecting);
+      },
+      {
+        root: null,
+        rootMargin: `${PREWARM_MARGIN_PX}px 0px ${PREWARM_MARGIN_PX}px 0px`,
+        threshold: 0,
+      },
+    );
+
+    io.observe(el);
+    return () => io.disconnect();
+  }, []);
+
+  return { ref, isVisible };
+}

package/src/library/VisibilitySelector.tsx

@@ -409,28 +409,69 @@ function CaretIcon() {
   );
 }
 
+/** Props for {@link VisibilityBadge}. */
+export interface VisibilityBadgeProps {
+  /** The visibility level to display. */
+  readonly visibility: ApiResourceVisibility;
+  /** Additional CSS classes applied to the chip. */
+  readonly className?: string;
+  /**
+   * When provided, the badge renders as a button and invokes this on
+   * activation. Detail headers use it as a shortcut into the Manage access
+   * dialog, so the at-a-glance chip is also the entry point to editing —
+   * the chip stays navigation-only (the dialog remains the single writer
+   * for both access axes). Omit it for a plain, non-interactive badge.
+   */
+  readonly onClick?: () => void;
+}
+
 /**
- * Read-only visibility indicator with a matching icon, covering all four
- * levels (Private / Organization / Platform / Public).
+ * Visibility indicator with a matching icon, covering all four levels
+ * (Private / Organization / Platform / Public).
  *
  * Rendered wherever the interactive {@link VisibilitySelector} is not
  * available — for viewers who lack `can_edit`, and while a permission check
  * is in flight — so a resource's visibility is always legible rather than
  * silently blank. Shares the chip styling with the selector trigger so the
  * read-only and editable states are visually consistent.
+ *
+ * With {@link VisibilityBadgeProps.onClick} the chip becomes an accessible
+ * button (hover + focus affordances, "Manage access" label) that hosts wire
+ * to their access-management surface; the badge itself never edits.
  */
 export function VisibilityBadge({
   visibility,
   className,
-}: {
-  readonly visibility: ApiResourceVisibility;
-  readonly className?: string;
-}) {
+  onClick,
+}: VisibilityBadgeProps) {
   const option = visibilityOption(visibility);
-  return (
-    <span className={cn(VISIBILITY_CHIP_CLASS, className)}>
+  const content = (
+    <>
       <VisibilityIcon tone={option.tone} className="size-2.5" />
       {option.label}
-    </span>
+    </>
+  );
+
+  if (onClick) {
+    return (
+      <button
+        type="button"
+        onClick={onClick}
+        title="Manage access"
+        aria-label={`${option.label} visibility — manage access`}
+        className={cn(
+          VISIBILITY_CHIP_CLASS,
+          "transition-colors hover:bg-accent-hover hover:text-foreground",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          className,
+        )}
+      >
+        {content}
+      </button>
+    );
+  }
+
+  return (
+    <span className={cn(VISIBILITY_CHIP_CLASS, className)}>{content}</span>
   );
 }