Feat/global widget enhancements 1

[MaryWylde]

No description provided.

[MaryWylde]

@claude, review this PR.

[claude]

Claude finished @MaryWylde's task in 2m 52s —— View job

---

PR Review: Feat/global widget enhancements 1

Tasks

• Gather repository context (CLAUDE.md)
• Review PR diff and changed files
• Analyze new library files (copilotAnalytics.ts, copilotEventsRead.ts, copilotSafety.ts, uxcgBridge.ts)
• Review API changes (concierge.ts, copilot/event.ts)
• Review admin UI pages (copilot sessions)
• Review widget changes (AskUxCore.tsx, api.ts)
• Post comprehensive review

---

This is a substantial PR (4027 additions) that introduces a full analytics pipeline, safety layer, admin observability UI, and major widget enhancements. The overall architecture is solid and well-commented. Below are issues found, grouped by severity.

---

🔴 Bugs / Type Errors

1. tab_close missing from CopilotEventKind in widget/src/api.ts

api.ts:316 defines:

export type CopilotEventKind =
  | 'clear' | 'card_click' | 'nav' | 'page_view'
  | 'dwell' | 'outbound_click' | 'auth_probe';

But AskUxCore.tsx calls postCopilotEvent({ kind: 'tab_close', ... }) in multiple places (lines ~1429, ~1509). TypeScript will reject this as 'tab_close' is not assignable to CopilotEventKind. The handler in event.ts:126 does accept it, so the fix is just adding 'tab_close' to the type union.

Fix this →

---

🟠 Style/Lint Violations (repo rules)

2. Wrong import order in UXCatLayout.tsx

The reorder in src/uxcore/layouts/UXCatLayout/UXCatLayout.tsx moves third-party imports (next/router, react, react-confetti-explosion, react-loading-skeleton) after @uxcore/components/* and @uxcore/data/* entries. The repo's ESLint-enforced order requires:

Third-party → ... → @hooks → @lib → @data → @icons → @components → @layouts

This is backwards and will likely fail the ESLint CI check.

Fix this →

3. Relative imports instead of @lib alias in concierge.ts

src/pages/api/concierge.ts:3–12 uses relative paths:

import { logTurn, markAuthLink } from '../../lib/copilotAnalytics';
import { ..., scrubPii } from '../../lib/copilotSafety';

The repo requires path aliases for cross-folder imports. The new event.ts in the same PR correctly uses @lib/copilotAnalytics. The concierge imports should match.

Fix this →

---

🟡 Code Quality / Maintainability

4. ensureSession is a silent no-op export — confusing

src/lib/copilotAnalytics.ts:81 exports ensureSession as a backwards-compat shim that does literally nothing. Any call site that calls it believing it seeds a session row will be silently wrong. At minimum, add a @deprecated JSDoc tag or a console.warn in NODE_ENV=development so callers can be found and cleaned up.

5. READ_LIB_REVISION = 'v4' is a debug artifact

src/lib/copilotEventsRead.ts:13: this was clearly added to bust the Next.js dev module cache during development. Keeping a manual 'v4' string in prod code means it will never be bumped correctly and creates false confidence. Remove it or replace with a build-time constant.

6. auth_probe in CopilotEventKind is a ghost entry

widget/src/api.ts:316: auth_probe is in the type union but event.ts has no case for it — it falls through to default: (no-op). It's either a placeholder that should have a // TODO comment, or it should be removed from the type until implemented.

7. debug field in getSessionDetail may expose service internals

src/lib/copilotEventsRead.ts:79 builds debug strings containing the full request URL, status codes, and raw response body. These are rendered on the admin page, which is dev-only gated. But the function itself has no scope restriction — any future caller outside the admin page would get a return value with an internal URL embedded in a string field. Consider keeping the debug info as a separate optional field and marking it clearly as admin-only.

---

🔵 Architecture / Design Notes

8. In-memory budget counter won't survive restarts

src/lib/copilotSafety.ts:16: dailyCalls is a module-level Map. The comment acknowledges "container restarts reset it." This is fine as documented, but if the container is restarted mid-day (deploy, OOM kill) the counter resets and the day's prior spend isn't counted. In a low-traffic scenario this is acceptable, but it's worth noting explicitly that the cap is "soft" — it only applies within a single process lifetime.

9. concierge.ts is now ~1900 lines

The file has grown substantially (was ~800 lines before this PR, now ~1900). The new functions isMetaTurn, inSameFamily, topSegment, familyOf, PROJECT_FAMILIES are good candidates to extract to src/lib/widget/ utilities alongside pageIdentity.ts for testability and to keep concierge.ts manageable.

10. Cookie missing Secure flag in event.ts

src/pages/api/copilot/event.ts:35:

`${COOKIE_NAME}=${sid}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${COOKIE_MAX_AGE}`

The Secure flag is absent. In an HTTPS-only production environment this is low-risk, but it's good hygiene to add Secure so the cookie isn't accidentally transmitted over plain HTTP (e.g., during local dev tunnels).

11. pageIdentity.ts: "200+" → "100+" factual change

src/lib/widget/pageIdentity.ts changes the UX Core bias count from "200+" to "100+" in the page blurb. Verify this reflects the actual current content count — the change is subtle and easy to miss in a large PR.

---

✅ What's Working Well

• Safety layer design: fail-open moderation (outage doesn't block widget), budget cap with clean UTC-day reset, PII scrub applied at every analytics boundary — solid defensive posture.
• Prompt injection fencing: the fence() wrapping + bilingual system-prompt hardening is a meaningful improvement.
• Thread ID architecture: localStorage-persisted, rotated on CLEAR, passed to server — clean separation from the HTTP-only sid cookie.
• Visibility-aware dwell tracking: using visibilityState correctly avoids inflated dwell time from backgrounded tabs.
• sendBeacon fallback in postCopilotEvent: good choice for page-unload events.
• UXCG sibling bridge: sensible first pass with a clear Phase 2 callout for bias→question inversion.
• Admin pages are properly dev-gated: isDevHost() returns { notFound: true } in prod — no access risk.
• HOMEPAGE_STARTERS / PAGE_LANDINGS: zero-latency, zero-hallucination first impressions are a good UX investment.

---

Summary: The critical fix needed before merging is the tab_close missing from CopilotEventKind (item 1 — TypeScript error). Items 2 and 3 (ESLint import order) should also be resolved to pass CI. Items 4–7 are code quality improvements that can be addressed in a follow-up.

[MaryWylde]

@claude shouldn't this be in api/ folder?

[claude]

Claude finished @MaryWylde's task in 34s —— View job

---

No — src/lib/widget/uxcgBridge.ts is correctly placed. Here's why:

Why it shouldn't be in src/pages/api/

src/pages/api/ is reserved for Next.js API route handlers — files that export a default handler(req, res) function that the framework routes HTTP requests to. If uxcgBridge.ts were placed there, Next.js would try to expose it as an HTTP endpoint (e.g. GET /api/uxcgBridge) and serve a 500 because there's no default export handler.

uxcgBridge.ts is a server-side library module, not a route handler. It:

• Fetches and caches UXCG question data from Strapi at process startup
• Exports getUxcgBridgeEntry(slug, lang) — a utility function consumed by concierge.ts
• Holds module-level in-memory state (cached, inFlight) that would be wrong to expose as an HTTP endpoint

The right analogy: copilotAnalytics.ts and copilotSafety.ts live in src/lib/ for the same reason — they're server-side utilities consumed by API routes, not routes themselves.

Is src/lib/widget/ the right sub-folder?

That's a reasonable follow-up question. It's currently grouped with pageIdentity.ts under src/lib/widget/, which is fine since it's widget-context logic. An equally valid home would be src/lib/ root (alongside copilotAnalytics.ts) since the module serves the concierge route, not the widget bundle. Either location works — the important thing is it stays out of src/pages/api/.

---

[MaryWylde]

@claude, what is this? Do we have this font?

[claude]

Claude finished @MaryWylde's task in 1m 6s —— View job

---

Tasks

• Gather context
• Read index.module.scss to identify fonts at lines 6 and 96
• Check if those fonts exist elsewhere in the project
• Post findings

---

Fonts in index.module.scss

Line 6 — font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;

This is the standard system UI font stack — not a custom font and not something that needs to be installed or imported. It resolves to whatever the OS provides:

OS	Font rendered
macOS / iOS	San Francisco (-apple-system / BlinkMacSystemFont)
Windows	Segoe UI
Android / Linux	Roboto
Everything else	fallback sans-serif

Zero new dependencies — no @font-face, no Google Fonts, no file download.

---

Line 96 — font-family: ui-monospace, SFMono-Regular, Menlo, monospace;

Same idea — a system monospace font stack:

OS	Font rendered
macOS (modern)	SF Mono (ui-monospace → SFMono-Regular)
macOS (older)	Menlo
Everything else	fallback monospace

Again, zero new dependencies. Also used consistently at lines 131, 205, and 228 in the same file for monospace-formatted content (session IDs, event payloads, etc.).

---

Are these consistent with the project?

The main site uses custom loaded fonts (Sarabun, Aldrich, Tomorrow, Cormorant Garamond, Source Serif, etc.) registered via @font-face in globals.scss. The admin pages deliberately don't use those — system fonts are correct here because:

1. The admin pages are dev-only internal tools (isDevHost() gate) — they don't need to match the public brand aesthetic.
2. System fonts load instantly, have no FOUT risk, and are more readable at small UI sizes (13px table rows, 12px mono labels).
3. This is the same pattern GitHub, Vercel, and most dev-tool UIs use for their dashboards.

Short answer: both fonts are fine and require nothing extra. They are intentionally different from the site's brand fonts, which is the right call for an admin tool.

[MaryWylde]

@claude, do we have this font, or is it something extra added?

[claude]

Claude finished @MaryWylde's task in 1m 0s —— View job

---

Font check: index.module.scss lines 6 & 96

Tasks

• Read index.module.scss
• Check project font definitions
• Post findings

---

Both fonts referenced in this file are OS/browser system font stacks — no installation, @font-face declaration, or import is needed. They are not extra dependencies.

Line 6 (.wrap):

font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;

This is the standard system UI font stack — resolves to San Francisco on macOS/iOS, Segoe UI on Windows, Roboto on Android. It's a CSS convention, not a custom font.

Line 96 (.mono):

font-family: ui-monospace, SFMono-Regular, Menlo, monospace;

This is the standard system monospace stack — resolves to SF Mono on macOS, Cascadia Code or Consolas on Windows. Again, no file needed.

---

Neither font needs to be added to the project. They're zero-overhead system fonts.

That said, these are not from the keepsimple design system. The rest of the site uses custom fonts declared in src/styles/globals.scss (Sarabun, Source-Serif, IBM Plex Mono, etc.). The admin page bypasses those and uses raw system fonts — which is intentional since the admin pages are dev-only internal tools (isDevHost() guard) and don't need to match the public-facing design system.

If you'd prefer the admin pages to use the project's design tokens (e.g. IBM Plex Mono for monospace, Sarabun for body), that would be a style consistency improvement but is not a bug.