@igstack/app-catalog-frontend-core 0.10.1 → 0.11.0

package/src/__tests__/modules/appCatalog/utils/resolveHelpers.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import type { Resource } from '@igstack/app-catalog-backend-core'
+import {
+  getAccessPrerequisiteChain,
+  getParentResource,
+} from '~/modules/appCatalog/utils/resolveHelpers'
+
+const r = (over: Partial<Resource> & { slug: string }): Resource =>
+  ({ id: over.slug, displayName: over.slug, ...over }) as Resource
+
+describe('getParentResource', () => {
+  it('returns undefined for a root resource', () => {
+    const root = r({ slug: 'aws-console' })
+    expect(getParentResource([root], root)).toBeUndefined()
+  })
+
+  it('finds the immediate parent by slug', () => {
+    const parent = r({ slug: 'aws-console' })
+    const child = r({ slug: 'acct-prod', parentSlug: 'aws-console' })
+    expect(getParentResource([parent, child], child)?.slug).toBe('aws-console')
+  })
+})
+
+describe('getAccessPrerequisiteChain (#38 two-step access)', () => {
+  it('is empty for a root resource', () => {
+    const root = r({
+      slug: 'gitlab',
+      accessRequest: { approvalMethodSlug: 'x' },
+    })
+    expect(getAccessPrerequisiteChain([root], root)).toEqual([])
+  })
+
+  it('is empty when the parent has NO access policy (nothing to require first)', () => {
+    const parent = r({ slug: 'aws-console' }) // no accessRequest
+    const child = r({ slug: 'acct', parentSlug: 'aws-console' })
+    expect(getAccessPrerequisiteChain([parent, child], child)).toEqual([])
+  })
+
+  it('returns the access-bearing parent for a nested resource', () => {
+    const parent = r({
+      slug: 'aws-console',
+      accessRequest: { approvalMethodSlug: 'it-helpdesk' },
+    })
+    const child = r({ slug: 'acct-prod', parentSlug: 'aws-console' })
+    const chain = getAccessPrerequisiteChain([parent, child], child)
+    expect(chain.map((c) => c.slug)).toEqual(['aws-console'])
+  })
+
+  it('orders multi-level chains root → nearest parent', () => {
+    const root = r({
+      slug: 'cloud',
+      accessRequest: { approvalMethodSlug: 'a' },
+    })
+    const mid = r({
+      slug: 'aws-console',
+      parentSlug: 'cloud',
+      accessRequest: { approvalMethodSlug: 'b' },
+    })
+    const leaf = r({ slug: 'acct', parentSlug: 'aws-console' })
+    const chain = getAccessPrerequisiteChain([root, mid, leaf], leaf)
+    expect(chain.map((c) => c.slug)).toEqual(['cloud', 'aws-console'])
+  })
+
+  it('does not loop on a cyclic parent reference', () => {
+    const a = r({
+      slug: 'a',
+      parentSlug: 'b',
+      accessRequest: { approvalMethodSlug: 'x' },
+    })
+    const b = r({
+      slug: 'b',
+      parentSlug: 'a',
+      accessRequest: { approvalMethodSlug: 'y' },
+    })
+    // must terminate
+    const chain = getAccessPrerequisiteChain([a, b], a)
+    expect(chain.length).toBeLessThanOrEqual(2)
+  })
+})

package/src/index.css

@@ -1,52 +1,59 @@
 /* @import url(./modules/resourceJump/ui/JumpMainButton.css); */
 @import 'tailwindcss';
+/* Warm, crafted type to match the hand-drawn logo (see issue #31 redesign):
+   Fraunces = characterful display serif, Nunito Sans = friendly readable body. */
+@import url('https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,500;9..144,600;9..144,700&family=Nunito+Sans:wght@400;500;600;700;800&display=swap');
 /* Other module imports this css, and we need to tell tailwind to scan our tsx files */
 @source ".";
 
 /* @import 'tw-animate-css'; */
 
 @layer base {
+  /* Warm "crayon" palette derived from the hand-drawn app-catalog logo
+     (orange #dc6827, amber #eca832, coral #e4724a, blue #3782c2, green #65a443)
+     on a cream paper background. Replaces the previous generic purple theme
+     that read as an AI template. See issue #31. */
   :root {
-    --background: oklch(0.9842 0.0034 247.8575);
-    --foreground: oklch(0.2795 0.0368 260.031);
-    --card: oklch(1 0 0);
-    --card-foreground: oklch(0.2795 0.0368 260.031);
-    --popover: oklch(1 0 0);
-    --popover-foreground: oklch(0.2795 0.0368 260.031);
-    --primary: oklch(0.5854 0.2041 277.1173);
-    --primary-foreground: oklch(1 0 0);
-    --secondary: oklch(0.9276 0.0058 264.5313);
-    --secondary-foreground: oklch(0.3729 0.0306 259.7328);
-    --muted: oklch(0.967 0.0029 264.5419);
-    --muted-foreground: oklch(0.551 0.0234 264.3637);
-    --accent: oklch(0.9299 0.0334 272.7879);
-    --accent-foreground: oklch(0.3729 0.0306 259.7328);
+    --background: oklch(0.9825 0.0125 84); /* warm cream paper */
+    --foreground: oklch(0.28 0.02 55); /* warm near-black ink */
+    --card: oklch(0.995 0.004 84);
+    --card-foreground: oklch(0.28 0.02 55);
+    --popover: oklch(0.995 0.004 84);
+    --popover-foreground: oklch(0.28 0.02 55);
+    --primary: oklch(0.62 0.17 45); /* logo orange #dc6827 */
+    --primary-foreground: oklch(0.99 0.01 84);
+    --secondary: oklch(0.94 0.018 80); /* warm sunk panel */
+    --secondary-foreground: oklch(0.36 0.03 55);
+    --muted: oklch(0.955 0.012 82);
+    --muted-foreground: oklch(0.52 0.025 60);
+    --accent: oklch(0.93 0.05 70); /* soft amber accent */
+    --accent-foreground: oklch(0.36 0.04 55);
     --destructive: oklch(0.6368 0.2078 25.3313);
     --destructive-foreground: oklch(1 0 0);
-    --border: oklch(0.8717 0.0093 258.3382);
-    --input: oklch(0.8717 0.0093 258.3382);
-    --ring: oklch(0.5854 0.2041 277.1173);
-    --chart-1: oklch(0.5854 0.2041 277.1173);
-    --chart-2: oklch(0.5106 0.2301 276.9656);
-    --chart-3: oklch(0.4568 0.2146 277.0229);
-    --chart-4: oklch(0.3984 0.1773 277.3662);
-    --chart-5: oklch(0.3588 0.1354 278.6973);
-    --sidebar: oklch(0.967 0.0029 264.5419);
-    --sidebar-foreground: oklch(0.2795 0.0368 260.031);
-    --sidebar-primary: oklch(0.5854 0.2041 277.1173);
-    --sidebar-primary-foreground: oklch(1 0 0);
-    --sidebar-accent: oklch(0.9299 0.0334 272.7879);
-    --sidebar-accent-foreground: oklch(0.3729 0.0306 259.7328);
-    --sidebar-border: oklch(0.8717 0.0093 258.3382);
-    --sidebar-ring: oklch(0.5854 0.2041 277.1173);
+    --border: oklch(0.9 0.018 80); /* warm hairline */
+    --input: oklch(0.9 0.018 80);
+    --ring: oklch(0.62 0.17 45);
+    --chart-1: oklch(0.62 0.17 45); /* orange */
+    --chart-2: oklch(0.62 0.14 230); /* blue #3782c2 */
+    --chart-3: oklch(0.68 0.14 135); /* green #65a443 */
+    --chart-4: oklch(0.75 0.14 75); /* amber #eca832 */
+    --chart-5: oklch(0.66 0.15 20); /* coral #e4724a */
+    --sidebar: oklch(0.955 0.012 82);
+    --sidebar-foreground: oklch(0.28 0.02 55);
+    --sidebar-primary: oklch(0.62 0.17 45);
+    --sidebar-primary-foreground: oklch(0.99 0.01 84);
+    --sidebar-accent: oklch(0.93 0.05 70);
+    --sidebar-accent-foreground: oklch(0.36 0.04 55);
+    --sidebar-border: oklch(0.9 0.018 80);
+    --sidebar-ring: oklch(0.62 0.17 45);
     --font-sans:
-      ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji',
+      'Nunito Sans', ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji',
       'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
-    --font-serif: Merriweather, serif;
+    --font-serif: 'Fraunces', Georgia, serif;
     --font-mono:
       ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
       'Courier New', monospace;
-    --radius: 0.5rem;
+    --radius: 0.875rem; /* rounder corners to match the friendly logo */
     --shadow-2xs: 0px 4px 8px -1px hsl(0 0% 0% / 0.05);
     --shadow-xs: 0px 4px 8px -1px hsl(0 0% 0% / 0.05);
     --shadow-sm:
@@ -73,44 +80,44 @@
     --eh-context-border: #ff7926;
   }
 
-  /* https://tweakcn.com/editor/theme */
+  /* Warm-dark equivalent of the crayon palette (see issue #31). */
   .dark {
-    --background: hsl(212.29deg 18.32% 13.93%);
-    --foreground: oklch(0.9288 0.0126 255.5078);
-    --card: oklch(0.2795 0.0368 260.031);
-    --card-foreground: oklch(0.9288 0.0126 255.5078);
-    --popover: oklch(0.2795 0.0368 260.031);
-    --popover-foreground: oklch(0.9288 0.0126 255.5078);
-    --primary: oklch(0.6801 0.1583 276.9349);
-    --primary-foreground: oklch(0.2077 0.0398 265.7549);
-    --secondary: oklch(0.3351 0.0331 260.912);
-    --secondary-foreground: oklch(0.8717 0.0093 258.3382);
-    --muted: oklch(0.2795 0.0368 260.031);
-    --muted-foreground: oklch(0.7137 0.0192 261.3246);
-    --accent: oklch(0.3729 0.0306 259.7328);
-    --accent-foreground: oklch(0.8717 0.0093 258.3382);
+    --background: oklch(0.19 0.012 60); /* warm charcoal, not blue-gray */
+    --foreground: oklch(0.93 0.012 84);
+    --card: oklch(0.23 0.014 58);
+    --card-foreground: oklch(0.93 0.012 84);
+    --popover: oklch(0.23 0.014 58);
+    --popover-foreground: oklch(0.93 0.012 84);
+    --primary: oklch(0.7 0.16 48); /* brightened logo orange for dark */
+    --primary-foreground: oklch(0.2 0.012 55);
+    --secondary: oklch(0.3 0.016 58);
+    --secondary-foreground: oklch(0.9 0.012 84);
+    --muted: oklch(0.26 0.014 58);
+    --muted-foreground: oklch(0.72 0.018 70);
+    --accent: oklch(0.34 0.03 60);
+    --accent-foreground: oklch(0.9 0.012 84);
     --destructive: oklch(0.6368 0.2078 25.3313);
     --destructive-foreground: oklch(0.2077 0.0398 265.7549);
-    --border: oklch(0.4461 0.0263 256.8018);
-    --input: oklch(0.4461 0.0263 256.8018);
-    --ring: oklch(0.6801 0.1583 276.9349);
-    --chart-1: oklch(0.6801 0.1583 276.9349);
-    --chart-2: oklch(0.5854 0.2041 277.1173);
-    --chart-3: oklch(0.5106 0.2301 276.9656);
-    --chart-4: oklch(0.4568 0.2146 277.0229);
-    --chart-5: oklch(0.3984 0.1773 277.3662);
-    --sidebar: oklch(0.2795 0.0368 260.031);
-    --sidebar-foreground: oklch(0.9288 0.0126 255.5078);
-    --sidebar-primary: oklch(0.6801 0.1583 276.9349);
-    --sidebar-primary-foreground: oklch(0.2077 0.0398 265.7549);
-    --sidebar-accent: oklch(0.3729 0.0306 259.7328);
-    --sidebar-accent-foreground: oklch(0.8717 0.0093 258.3382);
-    --sidebar-border: oklch(0.4461 0.0263 256.8018);
-    --sidebar-ring: oklch(0.6801 0.1583 276.9349);
+    --border: oklch(0.36 0.016 58);
+    --input: oklch(0.36 0.016 58);
+    --ring: oklch(0.7 0.16 48);
+    --chart-1: oklch(0.7 0.16 48);
+    --chart-2: oklch(0.66 0.13 230);
+    --chart-3: oklch(0.7 0.14 135);
+    --chart-4: oklch(0.78 0.14 75);
+    --chart-5: oklch(0.68 0.15 20);
+    --sidebar: oklch(0.23 0.014 58);
+    --sidebar-foreground: oklch(0.93 0.012 84);
+    --sidebar-primary: oklch(0.7 0.16 48);
+    --sidebar-primary-foreground: oklch(0.2 0.012 55);
+    --sidebar-accent: oklch(0.34 0.03 60);
+    --sidebar-accent-foreground: oklch(0.9 0.012 84);
+    --sidebar-border: oklch(0.36 0.016 58);
+    --sidebar-ring: oklch(0.7 0.16 48);
     --font-sans:
-      ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji',
+      'Nunito Sans', ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji',
       'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
-    --font-serif: Merriweather, serif;
+    --font-serif: 'Fraunces', Georgia, serif;
     --font-mono:
       ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
       'Courier New', monospace;

package/src/modules/appCatalog/hooks/useSessionSyncedState.ts

@@ -0,0 +1,83 @@
+import { useCallback, useState } from 'react'
+
+/**
+ * Options for useSessionSyncedState hook
+ */
+export interface UseSessionSyncedStateOptions<T> {
+  /** The sessionStorage key */
+  key: string
+  /** Default value when the stored value is absent */
+  defaultValue: T
+  /** Optional decoder to transform the stored string to a state value */
+  decode?: (storedValue: string) => T
+  /** Optional encoder to transform the state value to a string (return undefined to clear) */
+  encode?: (stateValue: T) => string | undefined
+}
+
+/**
+ * Hook for state that persists in `sessionStorage` instead of the URL.
+ *
+ * Why this exists (see #27): the catalog search value used to be
+ * synced to the URL (`?q=`) so it survived the per-route remount of
+ * `AppCatalogFiltersProvider` (#10). But `q` leaked into every shared/bookmarked
+ * app link. Backing the value with `sessionStorage` keeps the #10 guarantee —
+ * the value survives the remount and the auto-navigate to a single match — while
+ * keeping the URL clean.
+ *
+ * Key features vs {@link useUrlSyncedState}:
+ * - Initializes synchronously from `sessionStorage` on mount.
+ * - Writes synchronously in the setter (no async effect), which also removes the
+ *   effect-ordering race #10 fought (a child auto-navigate effect could run
+ *   before the provider's async state->URL sync).
+ * - Never navigates, so it never touches the URL.
+ *
+ * Defensive against environments without a functional `sessionStorage`
+ * (some CI jsdom setups) — falls back to plain in-memory state.
+ */
+export function useSessionSyncedState<T>({
+  key,
+  defaultValue,
+  decode,
+  encode,
+}: UseSessionSyncedStateOptions<T>): [T, (value: T) => void] {
+  const [state, setStateInternal] = useState<T>(() => {
+    try {
+      // The try/catch is the real guard against a missing/throwing
+      // sessionStorage (SSR, locked-down jsdom); the access itself is typed
+      // non-null, so no optional chaining is needed here.
+      const stored = globalThis.sessionStorage.getItem(key)
+      if (stored !== null) {
+        return decode ? decode(stored) : (stored as T)
+      }
+    } catch {
+      // sessionStorage unavailable — fall through to the default
+    }
+    return defaultValue
+  })
+
+  const setState = useCallback(
+    (value: T) => {
+      setStateInternal(value)
+      try {
+        const encoded = encode ? encode(value) : (value as string | undefined)
+        if (encoded === undefined) {
+          globalThis.sessionStorage.removeItem(key)
+        } else {
+          globalThis.sessionStorage.setItem(key, encoded)
+        }
+      } catch {
+        // sessionStorage unavailable — state still works in-memory
+      }
+    },
+    [key, encode],
+  )
+
+  return [state, setState]
+}
+
+/**
+ * sessionStorage key backing the catalog search value (#27). Exported so tests
+ * (and any tooling that needs to seed a "returning user" search) reference the
+ * same key as the provider.
+ */
+export const SEARCH_STORAGE_KEY = 'app-catalog:search'

package/src/modules/appCatalog/ui/components/AccessPrerequisiteChain.tsx

@@ -0,0 +1,89 @@
+import type { Resource } from '@igstack/app-catalog-backend-core'
+import { ArrowRight, KeyRound } from 'lucide-react'
+import { useAppCatalogContext } from '../../context/AppCatalogContext'
+import { getAccessPrerequisiteChain } from '../../utils/resolveHelpers'
+
+/**
+ * Two-step (prerequisite) access banner (#38 item D). When the viewed resource
+ * is a child whose ancestor(s) carry an access policy, the domain model says
+ * the user must obtain the parent's access FIRST. That chain is invisible
+ * otherwise, so surface it explicitly as ordered steps:
+ *
+ *   Step 1 — get access to <parent> (e.g. AWS Console via IT Helpdesk)
+ *   Step 2 — get access to THIS resource (contact its owner / access contacts)
+ *
+ * Renders nothing for root resources or children with no access-bearing parent.
+ * `onOpenParent` lets the user jump to the parent's full access instructions.
+ */
+export function AccessPrerequisiteChain({
+  resource,
+  onOpenParent,
+}: {
+  resource: Resource
+  onOpenParent?: (parent: Resource) => void
+}) {
+  const { resources } = useAppCatalogContext()
+  const chain = getAccessPrerequisiteChain(resources, resource)
+  if (chain.length === 0) return null
+
+  // Steps = each prerequisite ancestor (root→nearest), then this resource last.
+  const steps = [...chain, resource]
+
+  return (
+    <div
+      className="mt-6 rounded-lg border-[1.5px] border-primary/40 bg-primary/[0.03] p-4"
+      role="note"
+      aria-label="Access requires prerequisite steps"
+    >
+      <h3 className="mb-1 flex items-center gap-1.5 text-sm font-semibold text-foreground">
+        <KeyRound className="size-4 text-primary" />
+        Two-step access
+      </h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        This resource is nested — you need access to its parent first, then to
+        the resource itself.
+      </p>
+      <ol className="space-y-2">
+        {steps.map((r, i) => {
+          const isLast = i === steps.length - 1
+          return (
+            <li key={r.slug} className="flex items-start gap-2.5 text-sm">
+              <span className="mt-0.5 grid size-5 shrink-0 place-items-center rounded-full bg-primary text-[11px] font-bold text-primary-foreground">
+                {i + 1}
+              </span>
+              <span className="min-w-0">
+                <span className="text-muted-foreground">Get access to </span>
+                {isLast ? (
+                  <span className="font-semibold">this resource</span>
+                ) : onOpenParent ? (
+                  <button
+                    type="button"
+                    onClick={() => onOpenParent(r)}
+                    className="inline-flex items-center gap-1 font-semibold text-primary hover:underline"
+                  >
+                    {r.displayName}
+                    <ArrowRight className="size-3" />
+                  </button>
+                ) : (
+                  <span className="font-semibold">{r.displayName}</span>
+                )}
+                {!isLast && (
+                  <span className="text-muted-foreground">
+                    {' '}
+                    (see its access instructions)
+                  </span>
+                )}
+                {isLast && (
+                  <span className="text-muted-foreground">
+                    {' '}
+                    — details below.
+                  </span>
+                )}
+              </span>
+            </li>
+          )
+        })}
+      </ol>
+    </div>
+  )
+}

package/src/modules/appCatalog/ui/components/AccessRequestSection.tsx

@@ -153,9 +153,38 @@ export function AccessRequestSection({
   // Early return if no access request
   if (!accessRequest) return null
 
+  // Access UX (#31): some methods carry no clickable target — `noAccessRequired`
+  // (open), `unknown` (undocumented), and bare `custom` with no comments. The
+  // old UI rendered nothing for `custom`, leaving a blank/dead section. Instead
+  // surface an explicit, actionable line so the user is never stranded:
+  //  - open  → "No request needed — just open it."
+  //  - unknown / undocumented custom → route them to the owner (shown below).
+  const isOpen = approvalMethod?.type === 'noAccessRequired'
+  const hasWrittenSteps = Boolean(
+    accessRequest.requestPrompt || accessRequest.comments,
+  )
+  const isUndocumented =
+    approvalMethod?.type === 'unknown' ||
+    (approvalMethod?.type === 'custom' && !hasWrittenSteps)
+
   return (
-    <div className="mt-6 space-y-4">
-      <h3 className="text-sm font-medium">Access Request</h3>
+    <div className="mt-6 rounded-lg border-[1.5px] border-primary/40 bg-primary/[0.03] p-4 space-y-4">
+      <h3 className="text-sm font-semibold text-foreground">
+        How to get access
+      </h3>
+
+      {isOpen && (
+        <p className="text-sm font-medium text-primary">
+          ✓ Open to everyone — no request needed. Just open it.
+        </p>
+      )}
+
+      {isUndocumented && (
+        <p className="text-sm text-muted-foreground">
+          Access process not documented yet — contact the owner below to find
+          out.
+        </p>
+      )}
 
       {/* Approval Method */}
       {approvalMethod && approvalMethod.type !== 'custom' && (

package/src/modules/appCatalog/ui/components/OnboardingCard.tsx

@@ -53,7 +53,7 @@ export function OnboardingCard({
       </Button>
 
       <div className="pr-10">
-        <h2 className="text-lg font-bold mb-2">{title}</h2>
+        <h2 className="font-serif text-lg font-semibold mb-2">{title}</h2>
         <p className="text-muted-foreground mb-3 text-sm">{description}</p>
 
         <div className="bg-muted/50 rounded-lg p-3">

package/src/modules/appCatalog/ui/components/SubResourcesSection.tsx

@@ -25,6 +25,14 @@ import { markdownToPlainText } from '~/modules/appCatalog/utils/markdownToPlainT
 
 interface SubResourcesSectionProps {
   subResources: Resource[]
+  /**
+   * Initial filter text (#38 item C). When the user reached this app by
+   * searching a term that matched a sub-resource, seed the sub-resource filter
+   * with that term so the matched child is revealed instead of buried in a
+   * long list (e.g. searching "biom" → open AWS Console → the biomarker
+   * account is pre-filtered). Only applied when it actually matches a child.
+   */
+  initialSearch?: string
 }
 
 function getTierBadgeVariant(
@@ -90,9 +98,22 @@ function CopyAccountIdButton({ accountId }: { accountId: string }) {
 
 export function SubResourcesSection({
   subResources,
+  initialSearch,
 }: SubResourcesSectionProps) {
   const { groups } = useAppCatalogContext()
-  const [search, setSearch] = useState('')
+  // Seed the filter with the incoming query ONLY if it matches a child, so we
+  // reveal the matched sub-resource without hiding everything on a non-match.
+  const seededSearch = useMemo(() => {
+    const q = initialSearch?.trim().toLowerCase()
+    if (!q) return ''
+    const hit = subResources.some(
+      (sr) =>
+        sr.displayName.toLowerCase().includes(q) ||
+        (sr.aliases ?? []).some((a) => a.toLowerCase().includes(q)),
+    )
+    return hit ? initialSearch!.trim() : ''
+  }, [initialSearch, subResources])
+  const [search, setSearch] = useState(seededSearch)
   const [tierFilter, setTierFilter] = useState<string>('all')
 
   const uniqueTiers = useMemo(() => {

package/src/modules/appCatalog/ui/context/AppCatalogFiltersContext.tsx

@@ -2,6 +2,10 @@ import type { ReactNode } from 'react'
 import { createContext, use, useMemo } from 'react'
 import { useAppCatalogContext } from '../../context/AppCatalogContext'
 import { useUrlSyncedState } from '../../hooks/useUrlSyncedState'
+import {
+  SEARCH_STORAGE_KEY,
+  useSessionSyncedState,
+} from '../../hooks/useSessionSyncedState'
 import {
   decodeFiltersParam,
   encodeFiltersParam,
@@ -100,11 +104,13 @@ export function AppCatalogFiltersProvider({
     encode: encodeFiltersParam,
   })
 
-  // Search value is synced to URL (key `q`) so it survives navigation —
-  // e.g. auto-opening an app's detail page when the query narrows to one match
-  // (the filters provider is mounted per-route and remounts on navigation).
-  const [searchValue, setSearchValue] = useUrlSyncedState<string>({
-    key: 'q',
+  // Search value persists in sessionStorage (not the URL) so it survives the
+  // per-route remount of this provider — e.g. auto-opening an app's detail page
+  // when the query narrows to one match (#10) — WITHOUT leaking `?q=` into every
+  // shared/bookmarked app link (#27). The synchronous store read/write also
+  // removes the effect-ordering race the URL sync had (#10).
+  const [searchValue, setSearchValue] = useSessionSyncedState<string>({
+    key: SEARCH_STORAGE_KEY,
     defaultValue: '',
     decode: (value) => value,
     encode: (value) => (value === '' ? undefined : value),