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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igstack/app-catalog-frontend-core",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Frontend core library for App Catalog",
   "homepage": "https://github.com/lislon/app-catalog",
   "repository": {
@@ -134,8 +134,8 @@
     "vite-plugin-static-copy": "^3.1.4",
     "vite-plugin-svgr": "^4.2.0",
     "vitest": "^4.1.2",
-    "@igstack/app-catalog-backend-core": "0.10.1",
-    "@igstack/app-catalog-shared-core": "0.10.1"
+    "@igstack/app-catalog-backend-core": "0.12.0",
+    "@igstack/app-catalog-shared-core": "0.12.0"
   },
   "peerDependencies": {
     "react": "19.1.2",
@@ -144,7 +144,7 @@
     "vite": "^6.3.5",
     "vite-plugin-svgr": "^4.2.0"
   },
-  "gitHead": "3fd62ed2e0a2934d1f07f66cda16afb05f528515",
+  "gitHead": "34de03d23f3923a85c8a3b4d0bc6ff2d83c799d3",
   "scripts": {
     "build": "vite build",
     "build:lenient": "vite build --mode lenient",

package/src/__tests__/integration/appCatalog.integration.test.ts

@@ -71,6 +71,83 @@ describe('App Catalog Integration', () => {
     expect(appData.description).toBe('A test application')
   })
 
+  // Access UX (#31): "no access required" must be stated, not implied by a
+  // blank section. Previously a noAccessRequired/custom method rendered nothing.
+  it('states "open to everyone" for a no-access-required app', async () => {
+    const { ui } = await given(
+      magazine.custom(({ backendCfg }) => {
+        const method = backendCfg.withApprovalMethod({
+          type: 'noAccessRequired',
+          displayName: 'No Approval Needed',
+          config: {},
+        })
+        backendCfg.withApp({
+          displayName: 'Open App',
+          description: 'Anyone can use it',
+          accessRequest: { approvalMethodSlug: method.slug },
+        })
+      }),
+    )
+
+    await ui.catalog.openApp('Open App')
+    const access = ui.app.getAccessText()
+    expect(access).not.toBeNull()
+    expect(access!.toLowerCase()).toContain('no request')
+  })
+
+  // Access UX (#31): an undocumented method must route the user to the owner,
+  // never leave a blank/dead access section.
+  it('offers a fallback when the access process is undocumented', async () => {
+    const { ui } = await given(
+      magazine.custom(({ backendCfg }) => {
+        const method = backendCfg.withApprovalMethod({
+          type: 'unknown',
+          displayName: 'Unknown',
+          config: {},
+        })
+        backendCfg.withApp({
+          displayName: 'Mystery App',
+          description: 'Access process not written down',
+          accessRequest: { approvalMethodSlug: method.slug },
+        })
+      }),
+    )
+
+    await ui.catalog.openApp('Mystery App')
+    const access = ui.app.getAccessText()
+    expect(access).not.toBeNull()
+    expect(access!.toLowerCase()).toContain('not')
+  })
+
+  // Access UX (#31): each row has a secondary "open in new tab" launch action
+  // (the primary click opens detail). The launch link points at the app URL and
+  // must not also open the detail panel.
+  it('offers a secondary launch link on rows that has the app url', async () => {
+    const { ui } = await given(
+      magazine.custom(({ backendCfg }) => {
+        backendCfg.withApp({
+          displayName: 'Launchable App',
+          description: 'Has a url',
+          appUrl: 'https://launch.example.com',
+        })
+        // Second app so the single-result auto-open doesn't fire.
+        backendCfg.withApp({
+          displayName: 'Other App',
+          description: 'No url here',
+        })
+      }),
+    )
+
+    const link = ui.catalog.getLaunchLink('Launchable App')
+    expect(link).not.toBeNull()
+    expect(link!.getAttribute('href')).toBe('https://launch.example.com')
+    expect(link!.getAttribute('target')).toBe('_blank')
+    // The row without a URL has no launch link.
+    expect(ui.catalog.getLaunchLink('Other App')).toBeNull()
+    // Launch link is a secondary action — it does not open the detail panel.
+    expect(ui.catalog.isDetailPanelOpen()).toBe(false)
+  })
+
   // Test 5: Returning user — cached data + no onboarding + backend down
   it('returning user sees cached apps even when backend is unavailable', async () => {
     suppressConsole([/TRPC Error/, /Failed to fetch/])
@@ -152,6 +229,35 @@ describe('App Catalog Integration', () => {
     expect(subResources!.names).toContain('acct-staging')
   })
 
+  it('surfaces the parent app when searching for a sub-resource name (#38)', async () => {
+    const { ui } = await given(
+      magazine.custom(({ backendCfg }) => {
+        const app = backendCfg.withApp({
+          slug: 'aws-console',
+          displayName: 'AWS Console',
+          description: 'Cloud management console',
+        })
+        backendCfg.withSubResource({
+          appSlug: app.slug,
+          displayName: 'acct-payments-prod',
+          tier: 'prod',
+        })
+        backendCfg.withApp({
+          slug: 'unrelated',
+          displayName: 'Unrelated Tool',
+          description: 'Nothing to do with the query',
+        })
+      }),
+    )
+
+    // Query matches only a sub-resource name; the parent app must appear in the
+    // launcher search-morph results (cross-sub-resource search preserved).
+    await ui.catalog.search('acct-payments-prod')
+    const names = ui.catalog.getTableData().map((r) => r.name)
+    expect(names).toContain('AWS Console')
+    expect(names).not.toContain('Unrelated Tool')
+  })
+
   // Test 4: Malformed Response — HTML Instead of JSON
   it('shows error when backend returns HTML instead of JSON', async () => {
     suppressConsole([

package/src/__tests__/integration/appDeepLink.integration.test.ts

@@ -53,30 +53,53 @@ describe('App deep-link routing', () => {
     expect(ui.catalog.isDetailPanelOpen()).toBe(false)
   })
 
-  it('keeps the search text and focus after auto-navigating to a single match (#10)', async () => {
-    // Typing a query that narrows the catalog to exactly one app auto-opens
-    // that app's detail page. Before the fix the search value lived in
-    // component-local state (not the URL), and the filters provider remounts
-    // per route, so the input text (and focus) were wiped on navigation.
-    // This starts from an EMPTY search (initialRoute '/') and types — the real
-    // user flow — so it also guards the effect-ordering race where the child
-    // auto-navigate effect runs before the provider's async state→URL sync.
-    const { ui, router } = await given(magazine.full(), { initialRoute: '/' })
+  it('a single search match stays in the launcher morph — no auto-jump to /app (#38)', async () => {
+    // Regression (#38): a search narrowing to exactly one app used to auto-open
+    // that app's detail route, which — with the launcher — yanked the user out
+    // of the search-morph into the old grid+panel (reported: typing "biom"
+    // jumped straight to an app-detail page). The morph now shows the single
+    // match as a selectable row; the user opts in (click / ↵) to open it.
+    //
+    // Seed via sessionStorage (returning user who typed before this render):
+    // jsdom userEvent.type + useDeferredValue drops characters, orthogonal here.
+    const { ui, router } = await given(magazine.full(), {
+      initialRoute: '/',
+      seedSearch: 'jira',
+    })
 
-    await ui.catalog.search('jira')
+    // Stays on the launcher home — NO auto-navigation to the detail route.
+    await waitFor(() => {
+      expect(ui.catalog.getTableData().length).toBeGreaterThan(0)
+    })
+    expect(router.state.location.pathname).toBe('/')
+    expect(ui.catalog.getTableData().map((r) => r.name)).toContain('Jira')
+    // Search text preserved (sessionStorage-backed), no ?q leak.
+    expect(ui.catalog.getSearchInput().value).toBe('jira')
+    expect((router.state.location.search as { q?: string }).q).toBeUndefined()
 
-    // Auto-navigates to the single match, carrying the typed query into the URL
-    // as `q` (the fix). The regression this guards: before the fix `q` was never
-    // written, so on the per-route remount the input reset to '' and lost focus.
+    // Opting in (click) opens the detail.
+    await ui.catalog.openApp('Jira')
     await waitFor(() => {
       expect(router.state.location.pathname).toBe('/app/jira')
     })
+  })
 
-    // The query is persisted in the URL and the input reflects it — they stay in
-    // sync across the navigation, so the typed text is never lost.
-    const q = (router.state.location.search as { q?: string }).q
-    expect(q).toBeTruthy()
-    expect(ui.catalog.getSearchInput().value).toBe(q)
+  it('strips a legacy ?q= from the URL on the app detail route (#27)', async () => {
+    // Old shared links may still carry `?q=` (e.g. /app/jira?q=jira). `q` is
+    // still declared in the route search schema (so it validates), but the
+    // route's `stripSearchParams(['q'])` middleware rewrites the URL to a clean
+    // /app/jira on load. We no longer read `q` from the URL, so a bare deep-link
+    // doesn't repopulate the input from the query string.
+    const { ui, router } = await given(magazine.full(), {
+      initialRoute: '/app/jira?q=jira',
+    })
+
+    await waitFor(() => {
+      expect(ui.catalog.isDetailPanelOpen()).toBe(true)
+    })
+    expect(router.state.location.pathname).toBe('/app/jira')
+    expect(router.state.location.href).toBe('/app/jira')
+    expect((router.state.location.search as { q?: string }).q).toBeUndefined()
   })
 
   it('redirects /app/<alias> to the canonical /app/<slug> (replace, no back entry)', async () => {
@@ -102,17 +125,20 @@ describe('App deep-link routing', () => {
     expect(router.history.canGoBack()).toBe(false)
   })
 
-  it('populates the search input from ?q= on the app detail route (#10 read path)', async () => {
-    // The detail route must NOT strip `q` from the URL: landing on /app/<slug>
-    // with a query must repopulate the search input. This is what was actually
-    // broken — the route had no validateSearch schema, so `q` was dropped.
-    const { ui } = await given(magazine.full(), {
-      initialRoute: '/app/jira?q=jira',
+  it('restores the search input from sessionStorage on the app detail route (#10 read path, #27)', async () => {
+    // The #10 guarantee - landing on /app/<slug> repopulates the search input -
+    // now sources the query from sessionStorage instead of `?q=` (#27). Seed the
+    // store as a returning user would have (typed a search, then navigated), and
+    // assert the detail route restores it with no `q` in the URL.
+    const { ui, router } = await given(magazine.full(), {
+      initialRoute: '/app/jira',
+      seedSearch: 'jira',
     })
 
     await waitFor(() => {
       expect(ui.catalog.isDetailPanelOpen()).toBe(true)
     })
     expect(ui.catalog.getSearchInput().value).toBe('jira')
+    expect((router.state.location.search as { q?: string }).q).toBeUndefined()
   })
 })

package/src/__tests__/integration/appFreshness.integration.test.ts

@@ -11,7 +11,7 @@ const DAY = 24 * 60 * 60 * 1000
 const iso = (msAgo: number) => new Date(Date.now() - msAgo).toISOString()
 
 describe('App freshness line', () => {
-  it('shows a muted "Last checked" line when the app has freshness', async () => {
+  it('shows an "Updated" freshness line when the app has freshness', async () => {
     const { ui } = await given(
       magazine.full(({ backendCfg }) => {
         backendCfg.withApp({
@@ -24,7 +24,7 @@ describe('App freshness line', () => {
     )
 
     await waitFor(() => expect(ui.catalog.isDetailPanelOpen()).toBe(true))
-    expect(screen.getByText(/Last checked/i)).toBeInTheDocument()
+    expect(screen.getByText(/Updated/i)).toBeInTheDocument()
     // fresh → no stale note
     expect(screen.queryByText(/may be out of date/i)).toBeNull()
   })
@@ -58,6 +58,6 @@ describe('App freshness line', () => {
     )
 
     await waitFor(() => expect(ui.catalog.isDetailPanelOpen()).toBe(true))
-    expect(screen.queryByText(/Last checked/i)).toBeNull()
+    expect(screen.queryByText(/Updated/i)).toBeNull()
   })
 })

package/src/__tests__/integration/crossRefLinkListView.integration.test.ts

@@ -5,7 +5,7 @@ import { given } from './harness/given'
 import { magazine } from './mock-backend/magazines'
 
 // #25 regression: descriptions now carry markdown cross-reference links like
-// `[Example Portal](/app/example-portal)`. The detail panel renders them
+// `[Signatera Portal](/app/signatera-portal)`. The detail panel renders them
 // as real links, but the COMPACT surfaces (grid list preview / table row) show
 // `description` as plain text, so the raw markdown syntax leaked to users.
 // In clamped previews we render the visible text only — no bracket/paren
@@ -13,10 +13,10 @@ import { magazine } from './mock-backend/magazines'
 describe('Cross-reference links do not leak raw markdown in the list view (#25)', () => {
   const withCrossRefApp = magazine.full(({ backendCfg }) => {
     backendCfg.withApp({
-      slug: 'example-portals',
+      slug: 'natera-portals-ish',
       displayName: 'Portals Hub',
       description:
-        'See [Example Portal](/app/example-portal) and [Portal B](/app/portal-b).',
+        'See [Signatera Portal](/app/signatera-portal) and [Prospera Portal](/app/prospera-portal).',
     })
   })
 
@@ -30,20 +30,20 @@ describe('Cross-reference links do not leak raw markdown in the list view (#25)'
     expect(row).toBeDefined()
 
     // The clamped preview shows the visible text…
-    expect(row!.description).toContain('Example Portal')
-    expect(row!.description).toContain('Portal B')
+    expect(row!.description).toContain('Signatera Portal')
+    expect(row!.description).toContain('Prospera Portal')
     // …and NEVER leaks the raw markdown link syntax.
     expect(row!.description).not.toContain('](/app/')
-    expect(row!.description).not.toContain('[Example Portal]')
+    expect(row!.description).not.toContain('[Signatera Portal]')
   })
 
   it('does not render an interactive link inside the clamped list preview', async () => {
     await given(withCrossRefApp)
     await waitFor(() => {
-      expect(screen.getByText(/See Example Portal and/)).toBeInTheDocument()
+      expect(screen.getByText(/See Signatera Portal and/)).toBeInTheDocument()
     })
     // A clamped preview must not carry a navigational link that could break the
     // clamp/layout — the interactive cross-links live in the detail panel.
-    expect(screen.queryByRole('link', { name: 'Example Portal' })).toBeNull()
+    expect(screen.queryByRole('link', { name: 'Signatera Portal' })).toBeNull()
   })
 })

package/src/__tests__/integration/harness/given.tsx

@@ -25,6 +25,7 @@ import { MockBackendVerifier } from './MockBackendVerifier'
 import { getGlobalError } from '../tools/ErrorTools'
 import type { GlobalError } from '../tools/ErrorTools'
 import { browserState } from '../tools/BrowserState'
+import { SEARCH_STORAGE_KEY } from '~/modules/appCatalog/hooks/useSessionSyncedState'
 import { CatalogTools } from '../tools/CatalogTools'
 import { AppDetailTools } from '../tools/AppDetailTools'
 import { GalleryTools } from '../tools/GalleryTools'
@@ -60,7 +61,7 @@ export async function cleanupTestResources(): Promise<void> {
 
 export async function given(
   magazine: Magazine,
-  opts: { initialRoute?: string } = {},
+  opts: { initialRoute?: string; seedSearch?: string } = {},
 ): Promise<GivenResult> {
   // Clean up any previous resources
   await cleanupTestResources()
@@ -92,6 +93,13 @@ export async function given(
     localStorage.setItem(key, value)
   }
 
+  // Seed the persisted catalog search (#27): simulates a returning user who had
+  // typed a query before navigating. Backs the same sessionStorage key the
+  // provider reads, so the search input repopulates without any `?q=` in the URL.
+  if (opts.seedSearch !== undefined) {
+    sessionStorage.setItem(SEARCH_STORAGE_KEY, opts.seedSearch)
+  }
+
   // 5. Build network catalog from backend service, then apply overrides
   const catalog = makeNetworkReplyWithCatalog(service)
   for (const override of networkCfg.overrides) {

package/src/__tests__/integration/replacementLink.integration.test.ts

@@ -14,8 +14,11 @@ describe('Deprecated app "View replacement" link (#12)', () => {
     // Deep-link straight onto the deprecated Old Tool with an active search of
     // "old tool" — which does NOT match "New Tool", so the replacement is
     // absent from the filtered list (the exact condition that broke the link).
+    // The search is seeded via sessionStorage (#27) — it no longer rides in the
+    // URL as `?q=`.
     const { ui, router } = await given(magazine.full(), {
-      initialRoute: '/app/old-tool?q=old%20tool',
+      initialRoute: '/app/old-tool',
+      seedSearch: 'old tool',
     })
 
     await waitFor(() => {
@@ -41,7 +44,8 @@ describe('Deprecated app "View replacement" link (#12)', () => {
     // Hard navigation: /app/<slug> should render the app regardless of a
     // non-matching active search (browser-URL-like behavior).
     const { ui } = await given(magazine.full(), {
-      initialRoute: '/app/jira?q=zzz-no-match-zzz',
+      initialRoute: '/app/jira',
+      seedSearch: 'zzz-no-match-zzz',
     })
 
     await waitFor(() => {

package/src/__tests__/integration/searchDeprecatedFallback.integration.test.ts

@@ -5,42 +5,47 @@ import '@testing-library/jest-dom/vitest'
 import { given } from './harness/given'
 import { magazine } from './mock-backend/magazines'
 
-// #11: when a search returns 0 non-deprecated results, fall back to including
-// deprecated apps — show them, surface a notice, and auto-enable the
-// "Show Deprecated Apps" toggle. `magazine.full()` includes a deprecated app
-// "Old Tool" (slug old-tool) that is the only match for "old tool".
+// #11: when a search returns 0 non-deprecated results, fall back to showing
+// deprecated matches and surface a notice. In the launcher search-morph (#38)
+// there is no separate "Show Deprecated Apps" toggle (a grid-era control) —
+// the morph searches the full set and only labels the deprecated-only case.
+// `magazine.full()` includes a deprecated app "Old Tool" (slug old-tool) that
+// is the only match for "old tool".
 describe('Search fallback to deprecated apps (#11)', () => {
-  it('shows deprecated matches + notice + enables the toggle when 0 active results', async () => {
-    // Seed the query via the URL (`q`) to avoid the jsdom useDeferredValue +
-    // userEvent typing race. "old tool" matches ONLY the deprecated "Old Tool".
+  it('shows deprecated matches + notice when 0 active results', async () => {
+    // Seed the query via sessionStorage to avoid the jsdom useDeferredValue +
+    // userEvent typing race (#27 removed `?q=` from the URL). "old tool" matches
+    // ONLY the deprecated "Old Tool".
     const { ui } = await given(magazine.full(), {
-      initialRoute: '/?q=old%20tool',
+      initialRoute: '/',
+      seedSearch: 'old tool',
     })
 
-    // The fallback surfaces the deprecated match, shows the notice, and the
-    // "Show Deprecated Apps" toggle is auto-enabled.
+    // The fallback surfaces the deprecated match and shows the notice.
     await waitFor(() => {
       expect(ui.catalog.hasDeprecatedFallbackNotice()).toBe(true)
     })
     expect(ui.catalog.getTableData().map((r) => r.name)).toContain('Old Tool')
-    expect(ui.catalog.isShowDeprecatedChecked()).toBe(true)
   })
 
-  it('does not force deprecated results when the query has an active match', async () => {
-    const { ui } = await given(magazine.full(), { initialRoute: '/?q=Jira' })
+  it('does not show the fallback notice when the query has an active match', async () => {
+    const { ui } = await given(magazine.full(), {
+      initialRoute: '/',
+      seedSearch: 'Jira',
+    })
 
     await waitFor(() => {
       const names = ui.catalog.getTableData().map((r) => r.name)
       expect(names).toContain('Jira')
     })
-    // Active match exists → no fallback, no notice, toggle stays off.
+    // Active match exists → no deprecated-fallback notice.
     expect(ui.catalog.hasDeprecatedFallbackNotice()).toBe(false)
-    expect(ui.catalog.isShowDeprecatedChecked()).toBe(false)
   })
 
   it('keeps the normal empty state when nothing matches at all', async () => {
     const { ui } = await given(magazine.full(), {
-      initialRoute: '/?q=zzz-nothing-matches-zzz',
+      initialRoute: '/',
+      seedSearch: 'zzz-nothing-matches-zzz',
     })
 
     await waitFor(() => {

package/src/__tests__/integration/setup/testSetup.ts

@@ -19,6 +19,7 @@ afterEach(async () => {
   cleanup()
   await cleanupTestResources()
   localStorage.clear()
+  sessionStorage.clear()
 })
 
 // Mock window.matchMedia — required by embla-carousel in jsdom environment

package/src/__tests__/integration/skewWarning.integration.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { waitFor } from '@testing-library/react'
+import '@testing-library/jest-dom/vitest'
+
+import { given } from './harness/given'
+import { magazine } from './mock-backend/magazines'
+
+// The dev-only skew warning fires when resources loaded but 0 are top-level
+// (fingerprint of a frontend/backend-core version skew or stale service worker).
+describe('empty-catalog skew warning (dev-only)', () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>
+  const origDev = import.meta.env.DEV
+
+  beforeEach(() => {
+    // Force DEV so the guarded warning path runs under the test runner.
+    ;(import.meta.env as { DEV: boolean }).DEV = true
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+  afterEach(() => {
+    warnSpy.mockRestore()
+    ;(import.meta.env as { DEV: boolean }).DEV = origDev
+  })
+
+  it('warns when resources load but none are top-level (skew fingerprint)', async () => {
+    // Skew fixture: one resource, and it is a CHILD (parentSlug set) → rootResources === 0.
+    const skew = magazine.custom(({ backendCfg }) => {
+      backendCfg.withApp({
+        slug: 'child-only',
+        displayName: 'Child Only',
+        parentSlug: 'ghost-parent',
+      })
+    })
+    const { ui } = await given(skew)
+    await waitFor(() => {
+      expect(
+        warnSpy.mock.calls.some((c: unknown[]) =>
+          String(c[0]).includes('0 are top-level'),
+        ),
+      ).toBe(true)
+    })
+    // sanity: catalog rendered the empty state, not a crash
+    expect(ui.catalog).toBeDefined()
+  })
+
+  it('does NOT warn for a normal populated catalog', async () => {
+    const { ui } = await given(magazine.full())
+    await waitFor(() => {
+      expect(ui.catalog.getTableData().length).toBeGreaterThan(0)
+    })
+    expect(
+      warnSpy.mock.calls.some((c: unknown[]) =>
+        String(c[0]).includes('0 are top-level'),
+      ),
+    ).toBe(false)
+  })
+})

package/src/__tests__/integration/tools/AppDetailTools.ts

@@ -113,6 +113,19 @@ export class AppDetailTools {
     return { total, visible, names }
   }
 
+  /**
+   * Read the "How to get access" section text from the detail panel.
+   * Returns null if the section is not present.
+   */
+  getAccessText(): string | null {
+    const panel = this.getPanel()
+    const heading = this.findHeading(panel, 'How to get access')
+    if (!heading) return null
+    // The section is the heading plus its following content wrapper.
+    const container = heading.parentElement ?? heading
+    return container.textContent.trim()
+  }
+
   screenshots = {
     /**
      * Click the screenshot preview to open the gallery modal.

package/src/__tests__/integration/tools/CatalogTools.ts

@@ -11,24 +11,33 @@ export class CatalogTools {
 
   /**
    * Click an app row by display name.
+   * Works against both the table/grid view and the launcher home (#38), which
+   * renders app rows as buttons rather than a <table>.
    * Throws with list of visible apps if name not found.
    */
   async openApp(name: string): Promise<void> {
     const table = this.getCatalogTable()
-    if (!table) throw new Error('No catalog table found')
-    const rows = within(table).getAllByRole('row')
-
-    for (const row of rows) {
-      const nameEl = row.querySelector('.font-medium')
-      if (nameEl?.textContent.trim() === name) {
-        await this.user.click(row)
+    if (table) {
+      const rows = within(table).getAllByRole('row')
+      for (const row of rows) {
+        const nameEl = row.querySelector('.font-medium')
+        if (nameEl?.textContent.trim() === name) {
+          await this.user.click(row)
+          return
+        }
+      }
+    } else {
+      // Launcher home: rows are buttons titled "View <name>".
+      const btn = screen.queryByTitle(`View ${name}`)
+      if (btn) {
+        await this.user.click(btn)
         return
       }
     }
 
     const visibleNames = this.getTableData().map((r) => r.name)
     throw new Error(
-      `App "${name}" not found in table. Visible apps: [${visibleNames.join(', ')}]`,
+      `App "${name}" not found. Visible apps: [${visibleNames.join(', ')}]`,
     )
   }
 
@@ -63,7 +72,10 @@ export class CatalogTools {
           `Cannot read table — global error on page: ${bodyText.slice(0, 500)}`,
         )
       }
-      throw new Error('No table found on page')
+      // Launcher home (#38): no <table>; read the app row buttons instead.
+      const launcherRows = this.getLauncherRows()
+      if (launcherRows.length > 0) return launcherRows
+      throw new Error('No table or launcher rows found on page')
     }
 
     const rows = within(table).getAllByRole('row')
@@ -86,6 +98,18 @@ export class CatalogTools {
     return result
   }
 
+  /**
+   * The secondary "open in new tab" launch link for a row, by app name.
+   * Returns null if the row has no launch link.
+   */
+  getLaunchLink(name: string): HTMLAnchorElement | null {
+    // The launch link's aria-label starts with "Open <name> in a new tab" and
+    // may append the destination URL, e.g. "… in a new tab (foo.example.com)".
+    return screen.queryByLabelText<HTMLAnchorElement>(
+      new RegExp(`^Open ${name} in a new tab`),
+    )
+  }
+
   /**
    * Whether the right detail panel is currently visible.
    */
@@ -107,9 +131,12 @@ export class CatalogTools {
     return !!screen.queryByText(/showing deprecated matches/i)
   }
 
-  /** Whether the "No apps found" empty state is visible. */
+  /** Whether the "No apps found" empty state or search-morph "No results for" is visible. */
   isEmptyStateVisible(): boolean {
-    return !!screen.queryByText(/No apps found/i)
+    return (
+      !!screen.queryByText(/No apps found/i) ||
+      !!screen.queryByText(/No results for/i)
+    )
   }
 
   /**
@@ -119,6 +146,30 @@ export class CatalogTools {
     return !!screen.queryByText('Welcome to App Catalog')
   }
 
+  /**
+   * Read app rows from the launcher home (#38): buttons titled "View <name>".
+   * Name is the first `.font-semibold`/`.font-bold` span; description the
+   * `.text-muted-foreground` span. Deduped by name (an app can appear both in
+   * "Your apps" and "Browse all").
+   */
+  private getLauncherRows(): TableRow[] {
+    const buttons = Array.from(
+      document.querySelectorAll<HTMLElement>('button[title^="View "]'),
+    )
+    const seen = new Set<string>()
+    const result: TableRow[] = []
+    for (const btn of buttons) {
+      const name = (btn.getAttribute('title') ?? '')
+        .replace(/^View\s+/, '')
+        .trim()
+      if (!name || seen.has(name)) continue
+      seen.add(name)
+      const descEl = btn.querySelector('.text-muted-foreground')
+      result.push({ name, description: descEl?.textContent.trim() ?? '' })
+    }
+    return result
+  }
+
   /**
    * Get the main catalog table (first table on page, skipping sub-resource tables in detail panel).
    */