@igstack/app-catalog-frontend-core 0.9.0 → 0.9.2

package/dist/esm/modules/appCatalog/ui/components/MarkdownText.d.ts

@@ -1,7 +1,16 @@
 import { default as React } from 'react';
 /**
- * Renders a markdown link with security attributes (opens in a new tab,
- * no referrer/opener leakage). Shared so all catalog text fields render
+ * Renders a markdown link.
+ *
+ * Internal cross-references — a relative `/app/<slug>` pointing at another
+ * catalog entry — navigate WITHIN the app via the TanStack router (same tab,
+ * no full reload), so authors can cross-link entries with plain markdown
+ * `[Name](/app/<slug>)` (#25). The slug is validated against the loaded
+ * resources (canonical slug or a known alias); an unknown slug renders as
+ * plain text rather than a dead link.
+ *
+ * Everything else (external http/https links) opens in a new tab with
+ * `noopener noreferrer`, unchanged. Shared so all catalog text fields render
  * links identically.
  */
 export declare const MarkdownLink: ({ href, children, }: {

package/dist/esm/modules/appCatalog/ui/components/MarkdownText.js

@@ -1,18 +1,50 @@
-import { jsx } from "react/jsx-runtime";
+import { jsx, Fragment } from "react/jsx-runtime";
+import { useRouterState, Link } from "@tanstack/react-router";
 import ReactMarkdown from "react-markdown";
+import { useAppCatalogContext } from "../../context/AppCatalogContext.js";
+const INTERNAL_APP_LINK = /^\/app\/([^/?#]+)$/;
 const MarkdownLink = ({
   href,
   children
-}) => /* @__PURE__ */ jsx(
-  "a",
-  {
-    href,
-    target: "_blank",
-    rel: "noopener noreferrer",
-    className: "text-primary hover:underline",
-    children
+}) => {
+  const { resources } = useAppCatalogContext();
+  const pathname = useRouterState({ select: (s) => s.location.pathname });
+  const internalMatch = href == null ? void 0 : href.match(INTERNAL_APP_LINK);
+  if (internalMatch) {
+    const slug = decodeURIComponent(internalMatch[1] ?? "");
+    const exists = resources.some(
+      (r) => {
+        var _a;
+        return r.slug === slug || ((_a = r.aliases) == null ? void 0 : _a.includes(slug));
+      }
+    );
+    if (!exists) {
+      return /* @__PURE__ */ jsx(Fragment, { children });
+    }
+    const isCurrent = pathname === `/app/${slug}`;
+    return /* @__PURE__ */ jsx(
+      Link,
+      {
+        to: "/app/$slug",
+        params: { slug },
+        search: (prev) => prev,
+        "aria-current": isCurrent ? "page" : void 0,
+        className: "text-primary hover:underline",
+        children
+      }
+    );
   }
-);
+  return /* @__PURE__ */ jsx(
+    "a",
+    {
+      href,
+      target: "_blank",
+      rel: "noopener noreferrer",
+      className: "text-primary hover:underline",
+      children
+    }
+  );
+};
 function MarkdownText({
   children,
   className

package/dist/esm/modules/appCatalog/ui/components/MarkdownText.js.map

@@ -1 +1 @@
-{"version":3,"file":"MarkdownText.js","sources":["../../../../../../src/modules/appCatalog/ui/components/MarkdownText.tsx"],"sourcesContent":["import type React from 'react'\nimport ReactMarkdown from 'react-markdown'\n\n/**\n * Renders a markdown link with security attributes (opens in a new tab,\n * no referrer/opener leakage). Shared so all catalog text fields render\n * links identically.\n */\nexport const MarkdownLink = ({\n  href,\n  children,\n}: {\n  href?: string\n  children?: React.ReactNode\n}) => (\n  <a\n    href={href}\n    target=\"_blank\"\n    rel=\"noopener noreferrer\"\n    className=\"text-primary hover:underline\"\n  >\n    {children}\n  </a>\n)\n\n/**\n * Renders user-facing catalog text (descriptions, comments, prompts) as\n * markdown so links become clickable. Links use {@link MarkdownLink}.\n */\nexport function MarkdownText({\n  children,\n  className,\n}: {\n  children: string\n  className?: string\n}) {\n  return (\n    <span className={className}>\n      <ReactMarkdown components={{ a: MarkdownLink }}>{children}</ReactMarkdown>\n    </span>\n  )\n}\n"],"names":[],"mappings":";;AAQO,MAAM,eAAe,CAAC;AAAA,EAC3B;AAAA,EACA;AACF,MAIE;AAAA,EAAC;AAAA,EAAA;AAAA,IACC;AAAA,IACA,QAAO;AAAA,IACP,KAAI;AAAA,IACJ,WAAU;AAAA,IAET;AAAA,EAAA;AACH;AAOK,SAAS,aAAa;AAAA,EAC3B;AAAA,EACA;AACF,GAGG;AACD,SACE,oBAAC,QAAA,EAAK,WACJ,UAAA,oBAAC,eAAA,EAAc,YAAY,EAAE,GAAG,aAAA,GAAiB,SAAA,CAAS,EAAA,CAC5D;AAEJ;"}
+{"version":3,"file":"MarkdownText.js","sources":["../../../../../../src/modules/appCatalog/ui/components/MarkdownText.tsx"],"sourcesContent":["import { Link, useRouterState } from '@tanstack/react-router'\nimport type React from 'react'\nimport ReactMarkdown from 'react-markdown'\nimport { useAppCatalogContext } from '../../context/AppCatalogContext'\n\n/** Match a relative internal catalog link: `/app/<slug>` (slug only, no extra path). */\nconst INTERNAL_APP_LINK = /^\\/app\\/([^/?#]+)$/\n\n/**\n * Renders a markdown link.\n *\n * Internal cross-references — a relative `/app/<slug>` pointing at another\n * catalog entry — navigate WITHIN the app via the TanStack router (same tab,\n * no full reload), so authors can cross-link entries with plain markdown\n * `[Name](/app/<slug>)` (#25). The slug is validated against the loaded\n * resources (canonical slug or a known alias); an unknown slug renders as\n * plain text rather than a dead link.\n *\n * Everything else (external http/https links) opens in a new tab with\n * `noopener noreferrer`, unchanged. Shared so all catalog text fields render\n * links identically.\n */\nexport const MarkdownLink = ({\n  href,\n  children,\n}: {\n  href?: string\n  children?: React.ReactNode\n}) => {\n  const { resources } = useAppCatalogContext()\n  const pathname = useRouterState({ select: (s) => s.location.pathname })\n\n  const internalMatch = href?.match(INTERNAL_APP_LINK)\n  if (internalMatch) {\n    const slug = decodeURIComponent(internalMatch[1] ?? '')\n    const exists = resources.some(\n      (r) => r.slug === slug || r.aliases?.includes(slug),\n    )\n    // Unknown slug → render plain text, never a dead internal link.\n    if (!exists) {\n      return <>{children}</>\n    }\n    const isCurrent = pathname === `/app/${slug}`\n    return (\n      <Link\n        to=\"/app/$slug\"\n        params={{ slug }}\n        search={(prev) => prev}\n        aria-current={isCurrent ? 'page' : undefined}\n        className=\"text-primary hover:underline\"\n      >\n        {children}\n      </Link>\n    )\n  }\n\n  return (\n    <a\n      href={href}\n      target=\"_blank\"\n      rel=\"noopener noreferrer\"\n      className=\"text-primary hover:underline\"\n    >\n      {children}\n    </a>\n  )\n}\n\n/**\n * Renders user-facing catalog text (descriptions, comments, prompts) as\n * markdown so links become clickable. Links use {@link MarkdownLink}.\n */\nexport function MarkdownText({\n  children,\n  className,\n}: {\n  children: string\n  className?: string\n}) {\n  return (\n    <span className={className}>\n      <ReactMarkdown components={{ a: MarkdownLink }}>{children}</ReactMarkdown>\n    </span>\n  )\n}\n"],"names":[],"mappings":";;;;AAMA,MAAM,oBAAoB;AAgBnB,MAAM,eAAe,CAAC;AAAA,EAC3B;AAAA,EACA;AACF,MAGM;AACJ,QAAM,EAAE,UAAA,IAAc,qBAAA;AACtB,QAAM,WAAW,eAAe,EAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU;AAEtE,QAAM,gBAAgB,6BAAM,MAAM;AAClC,MAAI,eAAe;AACjB,UAAM,OAAO,mBAAmB,cAAc,CAAC,KAAK,EAAE;AACtD,UAAM,SAAS,UAAU;AAAA,MACvB,CAAC;;AAAM,iBAAE,SAAS,UAAQ,OAAE,YAAF,mBAAW,SAAS;AAAA;AAAA,IAAI;AAGpD,QAAI,CAAC,QAAQ;AACX,6CAAU,UAAS;AAAA,IACrB;AACA,UAAM,YAAY,aAAa,QAAQ,IAAI;AAC3C,WACE;AAAA,MAAC;AAAA,MAAA;AAAA,QACC,IAAG;AAAA,QACH,QAAQ,EAAE,KAAA;AAAA,QACV,QAAQ,CAAC,SAAS;AAAA,QAClB,gBAAc,YAAY,SAAS;AAAA,QACnC,WAAU;AAAA,QAET;AAAA,MAAA;AAAA,IAAA;AAAA,EAGP;AAEA,SACE;AAAA,IAAC;AAAA,IAAA;AAAA,MACC;AAAA,MACA,QAAO;AAAA,MACP,KAAI;AAAA,MACJ,WAAU;AAAA,MAET;AAAA,IAAA;AAAA,EAAA;AAGP;AAMO,SAAS,aAAa;AAAA,EAC3B;AAAA,EACA;AACF,GAGG;AACD,SACE,oBAAC,QAAA,EAAK,WACJ,UAAA,oBAAC,eAAA,EAAc,YAAY,EAAE,GAAG,aAAA,GAAiB,SAAA,CAAS,EAAA,CAC5D;AAEJ;"}

package/dist/esm/modules/appCatalog/ui/components/ViewToggle.d.ts

@@ -1,6 +1,12 @@
 /**
  * Compact segmented toggle for the header (Apps | Service Desks). Rendered in
  * the header's `middle` slot so it adds no header height. Uses router Links so
- * the active segment reflects the current route and each is deep-linkable.
+ * each segment is deep-linkable.
+ *
+ * The active segment is derived from the current pathname rather than a plain
+ * exact-match on the Link: the "Apps" tab must stay active on the app-detail
+ * routes (`/app/<slug>`) too, since the detail panel is part of the Apps view
+ * (#23). A plain `activeOptions={{ exact: true }}` on `to="/"` left both tabs
+ * inactive on `/app/<slug>`.
  */
 export declare function ViewToggle(): import("react/jsx-runtime").JSX.Element;

package/dist/esm/modules/appCatalog/ui/components/ViewToggle.js

@@ -1,7 +1,10 @@
 import { jsxs, jsx } from "react/jsx-runtime";
-import { Link } from "@tanstack/react-router";
+import { useRouterState, Link } from "@tanstack/react-router";
 import { cn } from "../../../../lib/utils.js";
 function ViewToggle() {
+  const pathname = useRouterState({ select: (s) => s.location.pathname });
+  const appsActive = pathname === "/" || pathname.startsWith("/app/");
+  const desksActive = pathname.startsWith("/service-desks");
   const segment = "inline-flex items-center rounded-md px-3 py-1 text-sm font-medium transition-colors";
   const active = "bg-background text-foreground shadow-sm";
   const inactive = "text-muted-foreground hover:text-foreground";
@@ -17,9 +20,8 @@ function ViewToggle() {
           {
             to: "/",
             "aria-label": "Apps",
-            className: cn(segment, inactive),
-            activeOptions: { exact: true },
-            activeProps: { className: cn(segment, active) },
+            "aria-current": appsActive ? "page" : void 0,
+            className: cn(segment, appsActive ? active : inactive),
             children: "Apps"
           }
         ),
@@ -28,8 +30,8 @@ function ViewToggle() {
           {
             to: "/service-desks",
             "aria-label": "Service Desks",
-            className: cn(segment, inactive),
-            activeProps: { className: cn(segment, active) },
+            "aria-current": desksActive ? "page" : void 0,
+            className: cn(segment, desksActive ? active : inactive),
             children: "Service Desks"
           }
         )

package/dist/esm/modules/appCatalog/ui/components/ViewToggle.js.map

@@ -1 +1 @@
-{"version":3,"file":"ViewToggle.js","sources":["../../../../../../src/modules/appCatalog/ui/components/ViewToggle.tsx"],"sourcesContent":["import { Link } from '@tanstack/react-router'\nimport { cn } from '~/lib/utils'\n\n/**\n * Compact segmented toggle for the header (Apps | Service Desks). Rendered in\n * the header's `middle` slot so it adds no header height. Uses router Links so\n * the active segment reflects the current route and each is deep-linkable.\n */\nexport function ViewToggle() {\n  const segment =\n    'inline-flex items-center rounded-md px-3 py-1 text-sm font-medium transition-colors'\n  const active = 'bg-background text-foreground shadow-sm'\n  const inactive = 'text-muted-foreground hover:text-foreground'\n\n  return (\n    <div\n      role=\"tablist\"\n      aria-label=\"View\"\n      className=\"inline-flex items-center gap-1 rounded-lg bg-muted p-[3px]\"\n    >\n      <Link\n        to=\"/\"\n        aria-label=\"Apps\"\n        className={cn(segment, inactive)}\n        activeOptions={{ exact: true }}\n        activeProps={{ className: cn(segment, active) }}\n      >\n        Apps\n      </Link>\n      <Link\n        to=\"/service-desks\"\n        aria-label=\"Service Desks\"\n        className={cn(segment, inactive)}\n        activeProps={{ className: cn(segment, active) }}\n      >\n        Service Desks\n      </Link>\n    </div>\n  )\n}\n"],"names":[],"mappings":";;;AAQO,SAAS,aAAa;AAC3B,QAAM,UACJ;AACF,QAAM,SAAS;AACf,QAAM,WAAW;AAEjB,SACE;AAAA,IAAC;AAAA,IAAA;AAAA,MACC,MAAK;AAAA,MACL,cAAW;AAAA,MACX,WAAU;AAAA,MAEV,UAAA;AAAA,QAAA;AAAA,UAAC;AAAA,UAAA;AAAA,YACC,IAAG;AAAA,YACH,cAAW;AAAA,YACX,WAAW,GAAG,SAAS,QAAQ;AAAA,YAC/B,eAAe,EAAE,OAAO,KAAA;AAAA,YACxB,aAAa,EAAE,WAAW,GAAG,SAAS,MAAM,EAAA;AAAA,YAC7C,UAAA;AAAA,UAAA;AAAA,QAAA;AAAA,QAGD;AAAA,UAAC;AAAA,UAAA;AAAA,YACC,IAAG;AAAA,YACH,cAAW;AAAA,YACX,WAAW,GAAG,SAAS,QAAQ;AAAA,YAC/B,aAAa,EAAE,WAAW,GAAG,SAAS,MAAM,EAAA;AAAA,YAC7C,UAAA;AAAA,UAAA;AAAA,QAAA;AAAA,MAED;AAAA,IAAA;AAAA,EAAA;AAGN;"}
+{"version":3,"file":"ViewToggle.js","sources":["../../../../../../src/modules/appCatalog/ui/components/ViewToggle.tsx"],"sourcesContent":["import { Link, useRouterState } from '@tanstack/react-router'\nimport { cn } from '~/lib/utils'\n\n/**\n * Compact segmented toggle for the header (Apps | Service Desks). Rendered in\n * the header's `middle` slot so it adds no header height. Uses router Links so\n * each segment is deep-linkable.\n *\n * The active segment is derived from the current pathname rather than a plain\n * exact-match on the Link: the \"Apps\" tab must stay active on the app-detail\n * routes (`/app/<slug>`) too, since the detail panel is part of the Apps view\n * (#23). A plain `activeOptions={{ exact: true }}` on `to=\"/\"` left both tabs\n * inactive on `/app/<slug>`.\n */\nexport function ViewToggle() {\n  const pathname = useRouterState({ select: (s) => s.location.pathname })\n\n  const appsActive = pathname === '/' || pathname.startsWith('/app/')\n  const desksActive = pathname.startsWith('/service-desks')\n\n  const segment =\n    'inline-flex items-center rounded-md px-3 py-1 text-sm font-medium transition-colors'\n  const active = 'bg-background text-foreground shadow-sm'\n  const inactive = 'text-muted-foreground hover:text-foreground'\n\n  return (\n    <div\n      role=\"tablist\"\n      aria-label=\"View\"\n      className=\"inline-flex items-center gap-1 rounded-lg bg-muted p-[3px]\"\n    >\n      <Link\n        to=\"/\"\n        aria-label=\"Apps\"\n        aria-current={appsActive ? 'page' : undefined}\n        className={cn(segment, appsActive ? active : inactive)}\n      >\n        Apps\n      </Link>\n      <Link\n        to=\"/service-desks\"\n        aria-label=\"Service Desks\"\n        aria-current={desksActive ? 'page' : undefined}\n        className={cn(segment, desksActive ? active : inactive)}\n      >\n        Service Desks\n      </Link>\n    </div>\n  )\n}\n"],"names":[],"mappings":";;;AAcO,SAAS,aAAa;AAC3B,QAAM,WAAW,eAAe,EAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU;AAEtE,QAAM,aAAa,aAAa,OAAO,SAAS,WAAW,OAAO;AAClE,QAAM,cAAc,SAAS,WAAW,gBAAgB;AAExD,QAAM,UACJ;AACF,QAAM,SAAS;AACf,QAAM,WAAW;AAEjB,SACE;AAAA,IAAC;AAAA,IAAA;AAAA,MACC,MAAK;AAAA,MACL,cAAW;AAAA,MACX,WAAU;AAAA,MAEV,UAAA;AAAA,QAAA;AAAA,UAAC;AAAA,UAAA;AAAA,YACC,IAAG;AAAA,YACH,cAAW;AAAA,YACX,gBAAc,aAAa,SAAS;AAAA,YACpC,WAAW,GAAG,SAAS,aAAa,SAAS,QAAQ;AAAA,YACtD,UAAA;AAAA,UAAA;AAAA,QAAA;AAAA,QAGD;AAAA,UAAC;AAAA,UAAA;AAAA,YACC,IAAG;AAAA,YACH,cAAW;AAAA,YACX,gBAAc,cAAc,SAAS;AAAA,YACrC,WAAW,GAAG,SAAS,cAAc,SAAS,QAAQ;AAAA,YACvD,UAAA;AAAA,UAAA;AAAA,QAAA;AAAA,MAED;AAAA,IAAA;AAAA,EAAA;AAGN;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igstack/app-catalog-frontend-core",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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.9.0",
-    "@igstack/app-catalog-shared-core": "0.9.0"
+    "@igstack/app-catalog-backend-core": "0.9.2",
+    "@igstack/app-catalog-shared-core": "0.9.2"
   },
   "peerDependencies": {
     "react": "19.1.2",
@@ -144,7 +144,7 @@
     "vite": "^6.3.5",
     "vite-plugin-svgr": "^4.2.0"
   },
-  "gitHead": "a27e7c29dd93494100f891f47b2bc4cea4091125",
+  "gitHead": "bffb2faf1feacac02c3c49096dbb5eb18f54cd12",
   "scripts": {
     "build": "vite build",
     "build:lenient": "vite build --mode lenient",

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

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+import { screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import '@testing-library/jest-dom/vitest'
+import { given } from './harness/given'
+import { magazine } from './mock-backend/magazines'
+
+// #25: when an app description references another catalog app via a relative
+// markdown link `[Name](/app/<slug>)`, it must navigate WITHIN the catalog
+// (TanStack Router, same tab) rather than opening a new browser tab. External
+// links stay `target=_blank`; links to unknown slugs render as plain text so
+// there are no dead internal links.
+describe('Cross-reference links between app entries (#25)', () => {
+  const withCrossRefApp = magazine.full(({ backendCfg }) => {
+    backendCfg.withApp({
+      slug: 'portals-hub',
+      displayName: 'Portals Hub',
+      description:
+        'See the [Jira](/app/jira) entry and the external [docs](https://example.com/docs). Also [Ghost](/app/no-such-app) which does not exist.',
+    })
+  })
+
+  it('navigates in-app (same tab, no new tab) when clicking an internal /app/<slug> link', async () => {
+    const { ui, router } = await given(withCrossRefApp, {
+      initialRoute: '/app/portals-hub',
+    })
+    await waitFor(() => {
+      expect(ui.catalog.isDetailPanelOpen()).toBe(true)
+    })
+
+    const jiraLink = screen.getByRole('link', { name: 'Jira' })
+    // Internal link must NOT open a new tab.
+    expect(jiraLink).not.toHaveAttribute('target', '_blank')
+    // It points at the router path (rendered as an href).
+    expect(jiraLink).toHaveAttribute('href', '/app/jira')
+
+    const user = userEvent.setup()
+    await user.click(jiraLink)
+
+    // In-app navigation: the router path changes and Jira's detail opens,
+    // without a full page reload / new tab.
+    await waitFor(() => {
+      expect(router.state.location.pathname).toBe('/app/jira')
+    })
+    await waitFor(() => {
+      expect(ui.app.getOpenTitle()).toContain('Jira')
+    })
+  })
+
+  it('sets aria-current="page" on an internal link that points at the open app', async () => {
+    const { ui } = await given(
+      magazine.full(({ backendCfg }) => {
+        backendCfg.withApp({
+          slug: 'self-ref',
+          displayName: 'Self Ref',
+          description: 'This links to [itself](/app/self-ref) recursively.',
+        })
+      }),
+      { initialRoute: '/app/self-ref' },
+    )
+    await waitFor(() => {
+      expect(ui.catalog.isDetailPanelOpen()).toBe(true)
+    })
+    const selfLink = screen.getByRole('link', { name: 'itself' })
+    expect(selfLink).toHaveAttribute('aria-current', 'page')
+  })
+
+  it('renders a link to a non-existent slug as plain text (no dead link)', async () => {
+    const { ui } = await given(withCrossRefApp, {
+      initialRoute: '/app/portals-hub',
+    })
+    await waitFor(() => {
+      expect(ui.catalog.isDetailPanelOpen()).toBe(true)
+    })
+    // "Ghost" text is present (as plain text merged into the paragraph)…
+    expect(screen.getAllByText(/Ghost.*does not exist/).length).toBeGreaterThan(
+      0,
+    )
+    // …but it is NOT a link (no dead internal link).
+    expect(screen.queryByRole('link', { name: 'Ghost' })).toBeNull()
+  })
+
+  it('keeps external links opening in a new tab', async () => {
+    const { ui } = await given(withCrossRefApp, {
+      initialRoute: '/app/portals-hub',
+    })
+    await waitFor(() => {
+      expect(ui.catalog.isDetailPanelOpen()).toBe(true)
+    })
+    const docsLink = screen.getByRole('link', { name: 'docs' })
+    expect(docsLink).toHaveAttribute('target', '_blank')
+    expect(docsLink).toHaveAttribute('rel', expect.stringContaining('noopener'))
+    expect(docsLink).toHaveAttribute('href', 'https://example.com/docs')
+  })
+})

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

@@ -123,3 +123,39 @@ describe('Service Desks view (#9)', () => {
     await waitFor(() => expect(search).toHaveFocus())
   })
 })
+
+// #23: the header "Apps" tab must stay active while viewing an app-detail route
+// (/app/<slug>) — the detail panel is part of the Apps view. Previously the Apps
+// link was active only on the exact "/" route, so /app/quicksight highlighted
+// neither tab.
+describe('ViewToggle active tab (#23)', () => {
+  const appsTab = () => screen.getByRole('link', { name: 'Apps' })
+  const deskTab = () => screen.getByRole('link', { name: 'Service Desks' })
+
+  it('activates the Apps tab on an app-detail route (/app/$slug)', async () => {
+    await given(magazine.full(), { initialRoute: '/app/jira' })
+
+    await waitFor(() =>
+      expect(appsTab()).toHaveAttribute('aria-current', 'page'),
+    )
+    expect(deskTab()).not.toHaveAttribute('aria-current')
+  })
+
+  it('activates the Apps tab on the root route', async () => {
+    await given(magazine.full(), { initialRoute: '/' })
+
+    await waitFor(() =>
+      expect(appsTab()).toHaveAttribute('aria-current', 'page'),
+    )
+    expect(deskTab()).not.toHaveAttribute('aria-current')
+  })
+
+  it('activates only Service Desks on the /service-desks route', async () => {
+    await given(magazine.full(), { initialRoute: '/service-desks' })
+
+    await waitFor(() =>
+      expect(deskTab()).toHaveAttribute('aria-current', 'page'),
+    )
+    expect(appsTab()).not.toHaveAttribute('aria-current')
+  })
+})

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

@@ -1,9 +1,23 @@
+import { Link, useRouterState } from '@tanstack/react-router'
 import type React from 'react'
 import ReactMarkdown from 'react-markdown'
+import { useAppCatalogContext } from '../../context/AppCatalogContext'
+
+/** Match a relative internal catalog link: `/app/<slug>` (slug only, no extra path). */
+const INTERNAL_APP_LINK = /^\/app\/([^/?#]+)$/
 
 /**
- * Renders a markdown link with security attributes (opens in a new tab,
- * no referrer/opener leakage). Shared so all catalog text fields render
+ * Renders a markdown link.
+ *
+ * Internal cross-references — a relative `/app/<slug>` pointing at another
+ * catalog entry — navigate WITHIN the app via the TanStack router (same tab,
+ * no full reload), so authors can cross-link entries with plain markdown
+ * `[Name](/app/<slug>)` (#25). The slug is validated against the loaded
+ * resources (canonical slug or a known alias); an unknown slug renders as
+ * plain text rather than a dead link.
+ *
+ * Everything else (external http/https links) opens in a new tab with
+ * `noopener noreferrer`, unchanged. Shared so all catalog text fields render
  * links identically.
  */
 export const MarkdownLink = ({
@@ -12,16 +26,45 @@ export const MarkdownLink = ({
 }: {
   href?: string
   children?: React.ReactNode
-}) => (
-  <a
-    href={href}
-    target="_blank"
-    rel="noopener noreferrer"
-    className="text-primary hover:underline"
-  >
-    {children}
-  </a>
-)
+}) => {
+  const { resources } = useAppCatalogContext()
+  const pathname = useRouterState({ select: (s) => s.location.pathname })
+
+  const internalMatch = href?.match(INTERNAL_APP_LINK)
+  if (internalMatch) {
+    const slug = decodeURIComponent(internalMatch[1] ?? '')
+    const exists = resources.some(
+      (r) => r.slug === slug || r.aliases?.includes(slug),
+    )
+    // Unknown slug → render plain text, never a dead internal link.
+    if (!exists) {
+      return <>{children}</>
+    }
+    const isCurrent = pathname === `/app/${slug}`
+    return (
+      <Link
+        to="/app/$slug"
+        params={{ slug }}
+        search={(prev) => prev}
+        aria-current={isCurrent ? 'page' : undefined}
+        className="text-primary hover:underline"
+      >
+        {children}
+      </Link>
+    )
+  }
+
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="text-primary hover:underline"
+    >
+      {children}
+    </a>
+  )
+}
 
 /**
  * Renders user-facing catalog text (descriptions, comments, prompts) as

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

@@ -1,12 +1,23 @@
-import { Link } from '@tanstack/react-router'
+import { Link, useRouterState } from '@tanstack/react-router'
 import { cn } from '~/lib/utils'
 
 /**
  * Compact segmented toggle for the header (Apps | Service Desks). Rendered in
  * the header's `middle` slot so it adds no header height. Uses router Links so
- * the active segment reflects the current route and each is deep-linkable.
+ * each segment is deep-linkable.
+ *
+ * The active segment is derived from the current pathname rather than a plain
+ * exact-match on the Link: the "Apps" tab must stay active on the app-detail
+ * routes (`/app/<slug>`) too, since the detail panel is part of the Apps view
+ * (#23). A plain `activeOptions={{ exact: true }}` on `to="/"` left both tabs
+ * inactive on `/app/<slug>`.
  */
 export function ViewToggle() {
+  const pathname = useRouterState({ select: (s) => s.location.pathname })
+
+  const appsActive = pathname === '/' || pathname.startsWith('/app/')
+  const desksActive = pathname.startsWith('/service-desks')
+
   const segment =
     'inline-flex items-center rounded-md px-3 py-1 text-sm font-medium transition-colors'
   const active = 'bg-background text-foreground shadow-sm'
@@ -21,17 +32,16 @@ export function ViewToggle() {
       <Link
         to="/"
         aria-label="Apps"
-        className={cn(segment, inactive)}
-        activeOptions={{ exact: true }}
-        activeProps={{ className: cn(segment, active) }}
+        aria-current={appsActive ? 'page' : undefined}
+        className={cn(segment, appsActive ? active : inactive)}
       >
         Apps
       </Link>
       <Link
         to="/service-desks"
         aria-label="Service Desks"
-        className={cn(segment, inactive)}
-        activeProps={{ className: cn(segment, active) }}
+        aria-current={desksActive ? 'page' : undefined}
+        className={cn(segment, desksActive ? active : inactive)}
       >
         Service Desks
       </Link>