e2e/tests/overview-page.spec.ts (1)

21-25: Missing logo-related assertions despite being in the PR checklist.

The PR description lists a logo visibility and scroll-to-top behavior check, but neither appears in this test. Consider adding:

test('logo is visible and scrolls page to top on click', async ({ page }) => {
  await page.evaluate(() => window.scrollTo(0, 500))
  await page.getByRole('img', { name: /LikeC4/ }).click() // adjust selector to match actual logo role/name
  await expect(page.evaluate(() => window.scrollY)).resolves.toBe(0)
})

Would you like me to draft the full logo test once the aria-label/role of the logo element is confirmed?

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@e2e/tests/overview-page.spec.ts` around lines 21 - 25, The test "header shows
burger, logo, search bar, and theme toggle" is missing the logo visibility and
click-scroll-to-top assertions called out in the PR checklist; add assertions to
verify the logo is visible and that clicking it scrolls the page to top: within
the same or a new test (e.g., "logo is visible and scrolls page to top on
click") programmatically scroll the page (window.scrollTo / page.evaluate),
assert the logo element (use page.getByRole('img', { name: /LikeC4/ }) or the
app's actual aria-label/role) is visible, click it, then assert window.scrollY
resolves to 0 to confirm the scroll-to-top behavior. Ensure the selector matches
the actual logo role/name before committing.

packages/likec4/app/src/routes/__root.tsx (1)

32-36: Optional: as Fqn | undefined cast is against the "avoid as" guideline.

The identical pattern already exists for relationships (line 31), so this is consistent, but both could be improved. Consider a .pipe(z.custom<Fqn>(...)) approach or a typed helper to avoid the cast.

♻️ Suggested alternative (applied identically to both fields)

-  focusOnElement: z.string()
-    .nonempty()
-    .optional()
-    .catch(undefined)
-    .transform(v => v as Fqn | undefined),
+  focusOnElement: z.string()
+    .nonempty()
+    .optional()
+    .catch(undefined) as z.ZodType<Fqn | undefined>,

Or, if a utility already exists:

const fqnParam = z.string().nonempty().optional().catch(undefined).transform(v => v as Fqn | undefined)
// reuse for both `relationships` and `focusOnElement`

As per coding guidelines: "Use TypeScript with explicit types; avoid using any and casts with as".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/routes/__root.tsx` around lines 32 - 36, Replace the
inline ".transform(v => v as Fqn | undefined)" cast on the focusOnElement field
with a typed validator/helper to avoid using "as": create a reusable schema
(e.g. fqnParam) or use z.custom<Fqn>(...) / .pipe(...) that validates/returns a
Fqn | undefined and reuse it for both relationships and focusOnElement so both
fields perform proper runtime validation without a TypeScript cast.

packages/likec4/app/src/components/search/OverviewSearch.tsx (1)

18-21: mod+f overrides the browser's native find-in-page.

Binding mod+f is a deliberate UX choice, but be aware it replaces the browser's built-in Ctrl/Cmd+F find functionality across the overview page. If users need to search raw page text, they'll have no keyboard shortcut for it.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/components/search/OverviewSearch.tsx` around lines 18
- 21, The current useHotkeys call in OverviewSearch.tsx binds 'mod+f' (['mod+f',
open, { preventDefault: true }]) which overrides the browser's native find;
either remove that binding or change it to a non-conflicting shortcut (e.g.
'mod+shift+f') and/or scope the handler so it only activates when the
OverviewSearch component is focused (keep useHotkeys and open but update the key
string or add a conditional activation option) to preserve the default
Ctrl/Cmd+F behavior.

packages/likec4/app/src/routes/_single/single-index.tsx (1)

58-58: Zero-width spacer is a fragile layout hack.

The invisible <div style={{ width: 0, height: 36 }}> is used to enforce minimum height alignment but is fragile — if the navigation panel's expected height changes, this value becomes stale silently.

Consider using minHeight on the parent instead, or a CSS variable if the navigation panel exposes one.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/routes/_single/single-index.tsx` at line 58, Remove
the fragile zero-width spacer div (the element with style {{ width: 0, height:
36 }} used as an invisible spacer) and instead enforce the height on the
containing element by applying a minHeight (or a CSS variable) to the parent
wrapper in single-index.tsx; for example, set a style or class on the parent
container element that uses minHeight: 36 (or reads from a CSS variable like
--nav-height exposed by the navigation panel) so layout stays correct when the
nav height changes. Ensure you delete the spacer div and update the parent
element's style/class (or add a CSS variable usage) so alignment is driven by
the container rather than a zero-width spacer.

packages/diagram/src/search/hooks.ts (1)

21-26: useCallback depends on the entire ctx object — consider narrowing.

ctx is a new object whenever any context field changes (even unrelated ones like pickViewFor), so the returned callback's identity is unnecessarily unstable. Depending on ctx.setSearchValue (which is a stable ref from useCallbackRef) would keep the callback identity stable across unrelated context changes.

♻️ Suggested narrower dependency

 export function useUpdateSearch() {
   const ctx = useSearchContext()
+  const { setSearchValue } = ctx
   return useCallback((search: string) => {
-    ctx.setSearchValue(search)
-  }, [ctx])
+    setSearchValue(search)
+  }, [setSearchValue])
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/hooks.ts` around lines 21 - 26, The useCallback
in useUpdateSearch currently depends on the whole ctx object from
useSearchContext, making the callback unstable when unrelated context fields
change; change the dependency to the stable setter by either destructuring
setSearchValue from useSearchContext or referencing ctx.setSearchValue directly
and use [ctx.setSearchValue] as the dependency so the returned callback (in
useUpdateSearch) only re-creates when setSearchValue changes.

packages/diagram/src/search/Search.tsx (2)

201-230: Missing displayName on SearchOverlayBody.

Search (Line 129) and SearchPanelContent (Line 199) both set displayName for React DevTools, but SearchOverlayBody does not. For consistency and easier debugging:

♻️ Add displayName

+SearchOverlayBody.displayName = 'SearchOverlayBody'

after Line 230.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/Search.tsx` around lines 201 - 230, The memoized
component SearchOverlayBody is missing a displayName which makes React DevTools
less clear; add a displayName assignment for the component (e.g., set
SearchOverlayBody.displayName = 'SearchOverlayBody') immediately after the
SearchOverlayBody declaration so it matches the other components like Search and
SearchPanelContent and improves debugging visibility.

---

135-199: SearchPanelContent is well-structured for reuse across diagram and overview search.

The JSDoc is helpful in noting the provider requirement. The conditional PickView render on Line 195 via ctx.pickViewFor is correct.

Minor nit: ctx is obtained on Line 137 but only used on Line 195 for pickViewFor. Since useSearchContext() subscribes this component to all context changes, every keystroke in the search input will re-render SearchPanelContent. This is likely acceptable given that the child components also subscribe to the context, but if you ever want to optimize, you could extract the PickView conditional into a small wrapper that reads only pickViewFor.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/Search.tsx` around lines 135 - 199,
SearchPanelContent subscribes to the entire search context via
useSearchContext() (ctx) but only uses ctx.pickViewFor at the bottom, causing
unnecessary re-renders on every context change; fix by extracting the
pickViewFor conditional into a tiny child component (e.g., PickViewPicker or
PickViewContainer) that calls useSearchContext(), reads only pickViewFor, and
returns pickViewFor ? <PickView elementFqn={pickViewFor} /> : null, then replace
the inline {ctx.pickViewFor && <PickView elementFqn={ctx.pickViewFor} />} with
the new wrapper so SearchPanelContent no longer re-renders for unrelated context
updates.

packages/diagram/src/search/XStateSearchAdapter.tsx (1)

8-8: Inconsistent useCallbackRef import source within the search module.

PickView.tsx imports useCallbackRef from '@mantine/hooks', while all other files in the search module (XStateSearchAdapter.tsx, Search.tsx, ElementsColumn.tsx) import from the local '../hooks/useCallbackRef'. For consistency across the module, align PickView.tsx to use the local implementation instead.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/XStateSearchAdapter.tsx` at line 8, PickView.tsx
currently imports useCallbackRef from '@mantine/hooks' but the rest of the
search module (XStateSearchAdapter.tsx, Search.tsx, ElementsColumn.tsx) use the
local implementation; update the import in PickView.tsx to import useCallbackRef
from '../hooks/useCallbackRef' so all files in the search module use the same
local hook implementation (no other code changes needed).

packages/likec4/app/src/components/ColorSchemeToggle.tsx (1)

25-26: Consider conditional rendering instead of CSS display toggling for the icons.

Both <IconMoonStars> and <IconSun> are always mounted; only their display property differs. Conditional rendering is the idiomatic React pattern and avoids unnecessary DOM nodes.

♻️ Proposed refactor

-      <IconMoonStars stroke={1.5} display={computedColorScheme === 'light' ? 'block' : 'none'} />
-      <IconSun stroke={1.5} display={computedColorScheme === 'dark' ? 'block' : 'none'} />
+      {computedColorScheme === 'light' ? <IconMoonStars stroke={1.5} /> : <IconSun stroke={1.5} />}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/components/ColorSchemeToggle.tsx` around lines 25 -
26, The icons IconMoonStars and IconSun in ColorSchemeToggle are always mounted
and toggled via CSS display; change to conditional rendering so only the active
icon is rendered: inside the ColorSchemeToggle render (where computedColorScheme
is used), replace the two always-mounted elements with a single conditional
expression that renders IconMoonStars when computedColorScheme === 'light' and
IconSun when computedColorScheme === 'dark', preserving props like stroke and
any aria/role attributes so behavior and accessibility remain unchanged.

packages/likec4/app/src/routes/_single/single-index.tsx (2)

77-77: Redundant responsive object — simplify pt={{ base: 'sm', sm: 'sm' }} to pt="sm".

Both breakpoints carry the same value; the object form adds noise without effect.

♻️ Proposed fix

-        pt={{ base: 'sm', sm: 'sm' }}
+        pt="sm"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/routes/_single/single-index.tsx` at line 77, Replace
the redundant responsive prop object used for padding-top — locate the JSX prop
pt={{ base: 'sm', sm: 'sm' }} (in the component rendering around
single-index.tsx) and simplify it to the scalar form pt="sm" to remove
unnecessary responsive verbosity while preserving the same styling.

---

58-58: Zero-width spacer div — intent unclear; consider using minHeight on the flex container.

<div style={{ width: 0, height: 36 }} aria-hidden /> silently forces a 36 px minimum row height. This is non-obvious and fragile. A cleaner alternative is setting minHeight directly on NavigationPanel.Body (or the wrapping flex container) so the intent is self-documenting.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/routes/_single/single-index.tsx` at line 58, The
inline zero-width spacer div (<div style={{ width: 0, height: 36 }} aria-hidden
/>) is being used to force row height; remove that div and instead apply a
minHeight (e.g., minHeight: 36) to the flex container that holds the
rows—preferably NavigationPanel.Body or its wrapping flex container—so the
layout intent is explicit; update the relevant JSX where the spacer div appears
and remove the aria-hidden spacer element.

packages/diagram/src/search/hooks.ts (1)

16-18: Consider adding an explicit return type to useNormalizedSearch.

Currently the return type is inferred as string. Adding an explicit annotation aligns with the project's guideline to use explicit types.

✨ Proposed fix

-export function useNormalizedSearch() {
+export function useNormalizedSearch(): string {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/hooks.ts` around lines 16 - 18, The hook
useNormalizedSearch currently relies on type inference; update its signature to
include an explicit return type (string) to satisfy the project's typing
guideline: annotate the function declaration (useNormalizedSearch) to return
string and ensure the return expression using
useDeferredValue(ctx.normalizedSearch) matches that type (ctx.normalizedSearch /
useDeferredValue usage remains unchanged).

packages/diagram/src/search/components/SearchInput.tsx (1)

26-42: useSearch() and useSearchContext() both call useContext(SearchContext) — one of the two calls is redundant.

useSearch internally calls useSearchContext(), so importing both causes SearchContext to be read twice per render. The component can get everything it needs from searchCtx directly.

♻️ Proposed fix

-import { useSearch } from '../hooks'
 import { useSearchContext } from '../SearchContext'

-  const [search, setSearch] = useSearch()
+  const [search, setSearch] = [searchCtx.searchValue, searchCtx.setSearchValue]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/components/SearchInput.tsx` around lines 26 - 42,
The component reads SearchContext twice: via useSearchContext() into searchCtx
and via useSearch() (which itself calls useSearchContext()); remove the
redundant useSearch() call and import, and instead pull needed values (e.g.,
search and setSearch) directly from searchCtx inside LikeC4SearchInput; update
any references to the local search/setSearch variables to use the properties
from searchCtx and remove the unused useSearch import and its [search,
setSearch] destructuring to avoid double context reads.

packages/diagram/src/search/Search.tsx (1)

70-77: selectIsOpened silently swallows errors — consider logging the return value.

The try/catch in selectIsOpened catches all exceptions and returns false, which means any actor state corruption would silently hide the search overlay. The console.error is good, but since this selector runs on every actor state change, a misbehaving actor could spam the console. Consider whether a single-fire warning or a more specific catch condition would be more appropriate.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/Search.tsx` around lines 70 - 77, The selector
selectIsOpened currently wraps all access in a broad try/catch which swallows
errors and may spam console.error; replace the blanket try/catch with a
defensive guard that checks the shape of the snapshot (e.g., verify s !==
null/undefined and typeof s.status === 'string' and typeof s.value === 'string')
before reading s.status and s.value, and only catch and log unexpected
exceptions (or log once) to avoid repeated console spam; update the function
that references SearchActorSnapshot (selectIsOpened) to perform these explicit
checks and emit a single, clear warning when an invalid snapshot is encountered
instead of returning false silently on every exception.

packages/likec4/app/src/routes/_single/single-index.tsx (1)

58-58: Consider using a more descriptive approach for the spacer element.

<div style={{ width: 0, height: 36 }} aria-hidden /> is a zero-width invisible spacer purely for layout alignment. A brief comment explaining its purpose (e.g., maintaining consistent header height) would aid future maintainers.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/routes/_single/single-index.tsx` at line 58, The
spacer div (<div style={{ width: 0, height: 36 }} aria-hidden />) is unclear—add
a short explanatory comment above it stating its purpose (e.g., "spacer to
maintain consistent header height for layout alignment") and either give it a
clear semantic name by replacing it with a small reusable Spacer component
(e.g., Spacer height={36}) or at minimum normalize attributes to
aria-hidden="true" and a CSS class (e.g., .spacer--header) so future maintainers
understand its role; update references in single-index.tsx accordingly.

packages/likec4/app/src/routes/__root.tsx (1)

32-36: as Fqn | undefined cast duplicates the same guideline violation in relationships.

Both focusOnElement and relationships use .transform(v => v as Fqn | undefined) purely to satisfy the TypeScript type, which is a bare as-cast the coding guidelines ask to avoid. Since Fqn is a branded string, a small refine or a shared helper would be more type-safe.

♻️ Extract a shared Zod schema for nullable Fqn params

Define once above searchParamsSchema:

+const fqnParam = z.string().nonempty().optional().catch(undefined).transform(
+  (v): Fqn | undefined => (v ? (v as Fqn) : undefined),
+)
+
 const searchParamsSchema = z.object({
   ...
   relationships: z.string()
-    .nonempty()
-    .optional()
-    .catch(undefined)
-    .transform(v => v as Fqn | undefined),
+    .nonempty()
+    .optional()
+    .catch(undefined)
+    .transform((v): Fqn | undefined => (v ? (v as Fqn) : undefined)),
   focusOnElement: z.string()
-    .nonempty()
-    .optional()
-    .catch(undefined)
-    .transform(v => v as Fqn | undefined),
+    .nonempty()
+    .optional()
+    .catch(undefined)
+    .transform((v): Fqn | undefined => (v ? (v as Fqn) : undefined)),

Or, if Fqn validation logic is ever centralised, replace both with a shared fqnParam schema entirely. This at minimum makes the return type explicit via a return-type annotation rather than a bare as.

As per coding guidelines, **/*.{ts,tsx}: "avoid using any and casts with as".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/routes/__root.tsx` around lines 32 - 36, The
transform cast ".transform(v => v as Fqn | undefined)" used in
searchParamsSchema fields focusOnElement and relationships violates the no-`as`
guideline; replace both with a shared Zod schema (e.g., fqnParam) that
validates/refines a branded Fqn (use .nonempty().optional().nullable() or
.refine(...) to enforce the Fqn shape) and export/use that in place of the
inline transforms so the resulting type is explicit without casting; update
searchParamsSchema to use fqnParam (or annotate the transform return type
explicitly) for both focusOnElement and relationships to remove the bare `as`
cast while keeping runtime validation.

packages/likec4/app/src/pages/ViewReact.tsx (1)

180-182: Optional: align error-level and catch-variable naming with sibling component.

FocusElementFromUrl uses console.warn and catch (e) while OpenRelationshipBrowserFromUrl uses console.error and catch (error). Both represent failed operations; aligning them avoids surprises when triaging logs.

🔧 Optional alignment

-    } catch (e) {
-      console.warn('focusOnElement failed:', e)
+    } catch (error) {
+      console.error('focusOnElement failed:', error)
     }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/pages/ViewReact.tsx` around lines 180 - 182, In
FocusElementFromUrl, change the catch block to use catch (error) and log with
console.error instead of console.warn so it matches the sibling
OpenRelationshipBrowserFromUrl; update the catch variable name from e to error
and replace console.warn('focusOnElement failed:', e) with a console.error call
that includes the error variable for consistent logging and easier triage.

packages/diagram/src/search/SearchContext.spec.ts (1)

43-46: Optional: add 'kind:a' boundary test to match the # prefix coverage.

The # prefix tests explicitly document the 1-char boundary ('#a' → ''). The kind: prefix tests jump from the empty case ('kind:') to a full word ('kind:system'), leaving the 1-char-after-prefix behavior ('kind:a') unspecified in the suite.

💡 Suggested addition

 it('handles kind: prefix normally', () => {
   expect(normalizeSearch('kind:')).toBe('kind:')
+  expect(normalizeSearch('kind:a')).toBe('kind:a')   // 1 char after prefix — document expected behavior
   expect(normalizeSearch('kind:system')).toBe('kind:system')
 })

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/SearchContext.spec.ts` around lines 43 - 46, Add
a one-character-after-prefix boundary test to the existing "handles kind: prefix
normally" spec: update the test for normalizeSearch (the test named 'handles
kind: prefix normally') to include an assertion that normalizeSearch('kind:a')
returns 'kind:a' to mirror the explicit 1-char coverage used for the '#' prefix
tests; this ensures the kind: prefix case is explicitly verified at the 1-char
boundary.

packages/diagram/src/search/components/PickView.tsx (1)

38-40: Thin wrapper can be removed.

closePickView is a single-expression wrapper with no extra logic; you can drop the indirection.

♻️ Simplification

-  const closePickView = () => {
-    ctx.closePickView()
-  }
+  const { closePickView } = ctx

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/components/PickView.tsx` around lines 38 - 40,
Remove the redundant thin wrapper function closePickView and call
ctx.closePickView directly wherever closePickView is referenced (e.g., event
handlers, props, or callbacks); delete the closePickView function declaration
and update all usages to use ctx.closePickView to eliminate the indirection
while preserving current behavior.

packages/likec4/app/src/routes/_single/single-index.tsx (1)

58-58: Consider replacing the invisible height-anchor div with CSS.

<div style={{ width: 0, height: 36 }} aria-hidden /> is a flex-height trick that requires reading the DOM diff to understand. A minHeight on NavigationPanel.Body (or an equivalent CSS token) would be more self-documenting.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/routes/_single/single-index.tsx` at line 58, Replace
the invisible spacer div (<div style={{ width: 0, height: 36 }} aria-hidden />)
with a declarative CSS rule on NavigationPanel.Body (or an equivalent component)
by adding a minHeight: 36px (or using the project's spacing token) to
NavigationPanel.Body's style or CSS class; remove the inline spacer and ensure
the component's CSS is documented/uses the design token so intent (height
anchor) is clear and no DOM-only spacer is required.

packages/diagram/src/search/hooks.ts (1)

21-25: useUpdateSearch wraps a stable setter in a redundant useCallback.

Since setSearchValue is either a useState setter or a useCallbackRef result (both have guaranteed stable identity), the useCallback layer adds no value and the hook is functionally equivalent to returning setSearchValue directly.

♻️ Optional simplification

 export function useUpdateSearch() {
-  const { setSearchValue } = useSearchContext()
-  return useCallback((search: string) => {
-    setSearchValue(search)
-  }, [setSearchValue])
+  return useSearchContext().setSearchValue
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/hooks.ts` around lines 21 - 25, The hook
useUpdateSearch wraps the stable setter setSearchValue in an unnecessary
useCallback; simplify by removing the useCallback wrapper and return
setSearchValue directly from useUpdateSearch (ensure the returned value
preserves the same signature/type as setSearchValue). Locate the useUpdateSearch
function and replace the useCallback-based return with a direct return of
setSearchValue.

packages/diagram/src/search/XStateSearchAdapter.tsx (1)

8-8: useCallbackRef implementations provide identical stable-reference guarantees.

Both the local packages/diagram/src/hooks/useCallbackRef.ts and @mantine/hooks versions return referentially stable functions using the same pattern (storing the callback in a ref and returning a stable wrapper). The useMemo deps comment on lines 66–71 is valid—all five callback refs are guaranteed stable across renders.

The package contains two sources: XStateSearchAdapter uses the local hook (correct for code reuse), while the older PickView.tsx uses @mantine/hooks. Consider consolidating to the local implementation for consistency across the package.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/XStateSearchAdapter.tsx` at line 8, The codebase
has two equivalent implementations of the same stable-callback hook—local
useCallbackRef (packages/diagram/src/hooks/useCallbackRef.ts) and the
`@mantine/hooks` version used in PickView.tsx—causing inconsistency; consolidate
by switching PickView.tsx to import and use the local useCallbackRef so both
components (XStateSearchAdapter and PickView) rely on the same implementation,
update the import in PickView.tsx to reference useCallbackRef, remove the
`@mantine/hooks` dependency usage for this hook, and ensure any existing comments
about stable references remain accurate (the useMemo dependency comment in
XStateSearchAdapter can be kept as-is).

packages/diagram/src/search/Search.tsx (6)

135-199: Destructure only pickViewFor from the context.

const ctx = useSearchContext() retrieves the full context object but only ctx.pickViewFor is consumed at line 195. Destructuring at the use-site is more idiomatic.

♻️ Proposed change

-  const ctx = useSearchContext()
+  const { pickViewFor } = useSearchContext()
 
   ...
 
-      {ctx.pickViewFor && <PickView elementFqn={ctx.pickViewFor} />}
+      {pickViewFor && <PickView elementFqn={pickViewFor} />}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/Search.tsx` around lines 135 - 199, Destructure
pickViewFor directly from the search context instead of grabbing the full ctx
object; replace "const ctx = useSearchContext()" with destructuring like "const
{ pickViewFor } = useSearchContext()" and then use pickViewFor in the JSX (e.g.,
{pickViewFor && <PickView elementFqn={pickViewFor} />}) so only the needed value
from useSearchContext is referenced in SearchPanelContent.

---

201-229: Add displayName to SearchOverlayBody for consistency.

Search and SearchPanelContent both have displayName set after their definitions; SearchOverlayBody is the only memo-wrapped component in this file without one, which makes React DevTools output inconsistent.

♻️ Proposed change

 })
+SearchOverlayBody.displayName = 'SearchOverlayBody'

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/Search.tsx` around lines 201 - 229,
SearchOverlayBody (the memo-wrapped component) lacks a displayName, causing
inconsistent React DevTools output; after the SearchOverlayBody definition add a
displayName property (e.g., SearchOverlayBody.displayName = 'SearchOverlayBody')
so it matches the pattern used for Search and SearchPanelContent and helps
debugging—locate the memo<{ searchActorRef: SearchActorRef }>(({}) => { ... })
definition and set the displayName immediately after it.

---

201-229: Add displayName to SearchOverlayBody for React DevTools consistency.

Search (line 129) and SearchPanelContent (line 199) both have displayName set after their memo calls. SearchOverlayBody is the only memo-wrapped component in this file without one.

♻️ Proposed change

 })
+SearchOverlayBody.displayName = 'SearchOverlayBody'

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/Search.tsx` around lines 201 - 229, Add a
displayName to the memo-wrapped component by setting the
SearchOverlayBody.displayName to "SearchOverlayBody" immediately after the memo
declaration so React DevTools shows a consistent name like the other components
(see Search and SearchPanelContent which already set displayName after their
memo calls).

---

131-134: Convert the block comment above SearchPanelContent to a JSDoc comment.

The existing /* */ block is not recognized by tooling as JSDoc. Since SearchPanelContent is a public export, the guidelines require /** */ style.

📝 Proposed change

-/**
- * The shared search panel content used by both diagram and overview search.
- * Must be rendered inside a SearchContext.Provider.
- */
+/**
+ * The shared search panel content used by both diagram and overview search.
+ *
+ * `@remarks` Must be rendered inside a {`@link` SearchContext.Provider}.
+ */

As per coding guidelines: "Use JSDoc to document public classes and methods."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/Search.tsx` around lines 131 - 134, The block
comment immediately above the exported SearchPanelContent component is using a
plain /* */ comment; change it to a JSDoc /** */ comment so tooling recognizes
it as documentation for the public export (i.e., replace the leading /* ... */
with /** ... */ and keep the same text directly above the SearchPanelContent
declaration).

---

137-137: Destructure only pickViewFor from the context.

ctx is declared but only ctx.pickViewFor is consumed. Destructuring at the point of use avoids an implicit dependency on the full context.

♻️ Proposed change

-  const ctx = useSearchContext()
+  const { pickViewFor } = useSearchContext()
 
   ...
 
-      {ctx.pickViewFor && <PickView elementFqn={ctx.pickViewFor} />}
+      {pickViewFor && <PickView elementFqn={pickViewFor} />}

Also applies to: 195-195

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/Search.tsx` at line 137, The code currently
assigns the whole context to ctx via useSearchContext() but only uses
ctx.pickViewFor; change the call to destructure the specific member: const {
pickViewFor } = useSearchContext(); then update references from ctx.pickViewFor
to pickViewFor and remove the unused ctx variable; apply the same change for the
other occurrence that similarly reads ctx (the second useSearchContext call that
only uses pickViewFor).

---

56-68: height: ['100%', '100cqh'] generates a breakpoint-scoped media query, not a CSS fallback.

Panda CSS uses a mobile-first breakpoint system and leverages min-width media queries when you write responsive styles. The two-element array ['100%', '100cqh'] therefore compiles to height: 100% at the base breakpoint and height: 100cqh only at sm+ (≈ 640 px), not as a same-breakpoint progressive-enhancement fallback.

If the intent was a browser-capability fallback (apply 100cqh everywhere, with 100% as the fallback for browsers without container-query support), the correct approach is to emit both rules under the same condition:

♻️ Proposed alternatives

-export const scrollAreaCss = css({
-  height: [
-    '100%',
-    '100cqh',
-  ],
+export const scrollAreaCss = css({
+  // Option A — single value; browsers without CQ support get 0 (usually acceptable here)
+  height: '100cqh',
+
+  // Option B — explicit `@supports` fallback if needed:
+  // height: '100%',
+  // '@supports (height: 100cqh)': { height: '100cqh' },

If the responsive (viewport-breakpoint) difference is intentional, please add a comment explaining the two viewport behaviours.

Based on learnings from Panda CSS official documentation: "Panda uses a mobile-first breakpoint system and leverages min-width media queries @media(min-width) when you write responsive styles."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/Search.tsx` around lines 56 - 68, The current
responsive array in scrollAreaCss (height: ['100%', '100cqh']) creates a
breakpoint media query instead of a same-breakpoint fallback; replace that array
with a fallback + capability check: set height: '100%' at the base, then add an
`@supports` block inside scrollAreaCss that sets height: '100cqh' (so browsers
that understand cqh get the 100cqh value while others keep 100%), keeping the
rest of the css ('.mantine-ScrollArea-viewport' and its children) unchanged.

packages/diagram/src/search/SearchContext.tsx (1)

23-29: Add JSDoc to the public useSearchContext hook.

normalizeSearch is documented (lines 31–34) but useSearchContext — also a public export — is not.

📝 Suggested JSDoc

+/**
+ * Returns the current {`@link` SearchContextValue} from the nearest SearchContext.Provider.
+ * `@throws` {Error} If called outside a SearchContext.Provider.
+ */
 export function useSearchContext(): SearchContextValue {

As per coding guidelines: "Use JSDoc to document public classes and methods."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/SearchContext.tsx` around lines 23 - 29, Add a
JSDoc block above the exported useSearchContext hook describing that it is a
public React hook which returns the current SearchContextValue, lists its return
type (SearchContextValue), and documents the runtime error behavior (throws if
called outside a SearchContext.Provider). Reference the exported function name
useSearchContext and the SearchContext.Provider in the doc comment so readers
know the hook must be used within that provider and what value it returns.

packages/diagram/src/search/hooks.ts (1)

11-25: Context delegation is clean; minor redundancy between useSearch and useUpdateSearch.

All three hooks correctly delegate to useSearchContext(). The useDeferredValue wrapping in useNormalizedSearch is a nice touch for keeping the UI responsive during rapid typing.

Note: useUpdateSearch (line 21-25) returns a useCallback-wrapped version of setSearchValue, which is already a stable ref from useCallbackRef in the adapter. This makes the useCallback layer redundant. Also, useSearch already exposes the same setter. If useUpdateSearch only exists for backward compatibility, consider documenting that or deprecating it in a future cleanup pass.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/hooks.ts` around lines 11 - 25, The
useUpdateSearch hook redundantly wraps setSearchValue in useCallback even though
setSearchValue is already stable (provided via useCallbackRef); remove the extra
useCallback and simply return the setSearchValue from useUpdateSearch
(referencing useUpdateSearch, useSearchContext, and setSearchValue) or, if you
want to preserve API surface only for backward compatibility, add a deprecation
comment/documentation on useUpdateSearch and forward-return the stable
setSearchValue without re-wrapping it.

packages/likec4/app/src/routes/_single/single-index.tsx (1)

58-58: Consider adding a brief comment for the zero-width spacer.

<div style={{ width: 0, height: 36 }} aria-hidden /> is a layout trick to enforce minimum row height, but its purpose isn't self-evident. A short inline comment (e.g., {/* height anchor for nav panel */}) would help future readers.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/routes/_single/single-index.tsx` at line 58, Add a
short inline comment explaining the purpose of the zero-width spacer div to
clarify its role as a height anchor for the nav/row; update the JSX element <div
style={{ width: 0, height: 36 }} aria-hidden /> in single-index.tsx (locate the
zero-width spacer) to include a brief comment such as {/* height anchor for nav
panel */} immediately adjacent to the element so future readers understand its
layout purpose.

packages/diagram/src/search/hooks.ts (1)

21-26: useCallback wrapping setSearchValue may be simplified away.

setSearchValue is destructured from the context (which should provide a stable reference, e.g., from useState). Wrapping it in useCallback with [setSearchValue] as the only dependency adds an allocation but doesn't change observable behaviour. The hook can simply return setSearchValue directly.

♻️ Optional simplification

 export function useUpdateSearch() {
   const { setSearchValue } = useSearchContext()
-  return useCallback((search: string) => {
-    setSearchValue(search)
-  }, [setSearchValue])
+  return setSearchValue
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/hooks.ts` around lines 21 - 26, The hook
useUpdateSearch unnecessarily wraps the stable context setter setSearchValue in
useCallback; simplify by returning setSearchValue directly from useUpdateSearch
(remove the useCallback wrapper and its dependency array) and remove the unused
import of useCallback, referencing useUpdateSearch, useSearchContext and
setSearchValue to locate the change.

packages/diagram/src/search/SearchContext.spec.ts (1)

30-41: Coverage is solid; consider adding a "##" edge case.

The hash-rule (startsWith('#') && length <= 2) is well-tested for '#' and '#a'. A '##' input (two hashes, length 2) is also covered by the same branch and returns '', but isn't explicitly exercised.

✅ Optional additional test

  it('returns empty string for "#a" (hash + single char)', () => {
    expect(normalizeSearch('#a')).toBe('')
  })
+
+ it('returns empty string for "##" (two hashes, length ≤ 2)', () => {
+   expect(normalizeSearch('##')).toBe('')
+ })

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/SearchContext.spec.ts` around lines 30 - 41, Add
a unit test case that verifies normalizeSearch returns an empty string for the
two-hash edge case "##"; specifically, in SearchContext.spec.ts add an it block
similar to the existing tests that calls normalizeSearch('##') and expects '' so
the branch guarded by startsWith('#') && length <= 2 (handled in
normalizeSearch) is explicitly exercised.

packages/diagram/src/search/components/PickView.tsx (1)

38-40: Trivial closePickView wrapper can be inlined.

The one-line wrapper adds no value; ctx.closePickView can be used directly at each call site.

♻️ Proposed simplification

-  const closePickView = () => {
-    ctx.closePickView()
-  }

Then replace the three usages:

-          closePickView()
+          ctx.closePickView()

-        onClick={e => {
-          e.stopPropagation()
-          closePickView()
-        }}>
+        onClick={e => {
+          e.stopPropagation()
+          ctx.closePickView()
+        }}>

-              onClick={(e) => {
-                e.stopPropagation()
-                closePickView()
-              }}>
+              onClick={(e) => {
+                e.stopPropagation()
+                ctx.closePickView()
+              }}>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/diagram/src/search/components/PickView.tsx` around lines 38 - 40,
Remove the trivial one-line wrapper closePickView and call ctx.closePickView
directly at each usage site; locate the closePickView declaration in
PickView.tsx (const closePickView = () => { ctx.closePickView() }) and delete
it, then replace any references to closePickView with ctx.closePickView to
simplify the code.

packages/likec4/app/src/routes/_single/single-index.tsx (1)

39-74: New sticky header with navigation — looks good overall.

The sticky header with backdrop blur, burger menu, logo, search, and theme toggle is well-composed. Minor note: the zero-width spacer <div style={{ width: 0, height: 36 }} aria-hidden /> on line 58 relies on a magic number for height alignment. Consider extracting this to a named constant or comment explaining what it matches, so it doesn't silently drift if NavigationPanel.Body heights change.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/app/src/routes/_single/single-index.tsx` around lines 39 -
74, The zero-width spacer div used to vertically align the header items
(currently <div style={{ width: 0, height: 36 }} aria-hidden />) relies on a
magic height (36) that can drift; replace this literal with a named constant
(e.g., NAV_BODY_HEIGHT or HEADER_ICON_SIZE) or derive the height from a shared
CSS variable and use that constant/variable in the style or class, update any
relevant references in NavigationPanel.Body or the surrounding header JSX so the
spacer remains consistent if sizes change, and add a short comment explaining
what the constant matches (logo/burger/search height) for future
maintainability.