feat: Client-side profile recommendation engine for Capacitor/direct mode

[hessius]

Summary

Port the Python recommendation engine to TypeScript so "Find Similar Profiles" and tag-based recommendations work in the native iOS app (Capacitor/direct mode) without requiring the Python backend.

Problem

In Capacitor/direct mode, DirectModeInterceptor stubbed both /api/profiles/find-similar and /api/profiles/recommend with empty { recommendations: [] } responses. The feature was flagged as enabled in featureFlags.ts but silently returned no results.

Solution

New files (1,092 lines added)

• profileAnalysis.ts — Unified profile structural analysis module. Faithful TypeScript port of Python _extract_fingerprint() and _extract_name_tags() from profile_recommendation_service.py. Extracts control mode, technique tags, peak pressure, temperature, weight, and structural features from profile stages.

• profileRecommendation.ts — Client-side scoring engine. Same algorithm as Python backend: structure (35%), tags (25%), weight (15%), pressure (15%), temperature (10%). Pure functions, no caching. Exports findSimilarProfiles() and getRecommendations().

• profileAnalysis.test.ts + profileRecommendation.test.ts — 65 parity tests using the same 5 fixture profiles as Python test_recommendations.py. Validates fingerprint extraction, name tag extraction, scoring, ranking, and edge cases.

Modified files

• DirectModeInterceptor.ts — Replaced empty stubs with client-side engine calls. On recommendation requests, fetches full profile list from machine via /api/v1/profile/list, runs scoring, returns results.

Testing

• ✅ 786 frontend tests pass (65 new + 721 existing)
• ✅ Build succeeds
• ✅ App built and deployed to iPhone 14

Related

• Closes feat: Client-side profile recommendation engine + structural auto-tagging #398
• See audit: Horizontal review of DirectModeInterceptor feature parity #399 (horizontal feature parity audit)
• See feat: AI-generated tags during profile description generation #400 (AI tag enrichment, deferred to v2.5.0)

[Copilot]

Pull request overview

Ports the backend profile recommendation logic to the client so recommendations and “Find Similar Profiles” work in Capacitor/direct mode (no Python backend), and updates UI to display richer recommendation metadata.

Changes:

• Added TypeScript profile analysis + scoring engine with parity tests.
• Updated DirectModeInterceptor to serve /api/profiles/find-similar and /api/profiles/recommend using the client-side engine in direct/native mode.
• Enhanced recommendations UI (match reason badges, score badge colors, profile images) and added new tag categories/styles.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
apps/web/src/views/FormView.tsx	Adds optional callback to open a recommended profile from the form view.
apps/web/src/services/interceptor/DirectModeInterceptor.ts	Replaces empty recommendation stubs with client-side scoring backed by machine profile list fetch.
apps/web/src/lib/tags.ts	Adds technique/temperature tag categories + helpers for match-reason and score badge styling.
apps/web/src/lib/profileAnalysis.ts	New unified structural fingerprint + keyword extraction module (TS port).
apps/web/src/lib/profileAnalysis.test.ts	New parity tests for fingerprint and name-tag extraction.
apps/web/src/lib/profileRecommendation.ts	New client-side scoring + recommendation APIs (TS port).
apps/web/src/lib/profileRecommendation.test.ts	New parity/ranking tests for recommendations and similarity.
apps/web/src/index.css	Adds CSS classes for new tag categories and score badges.
apps/web/src/hooks/useSoundEffects.ts	Adjusts global delegation sound mapping for back/close interactions.
apps/web/src/components/ui/dialog.tsx	Updates close button styling and adds data-sound="close".
apps/web/src/components/ProfileRecommendations.tsx	Revamps recommendation cards (images, match badges, clickable selection).
apps/web/src/components/FindSimilarOverlay.tsx	Revamps “find similar” overlay cards (images, match badges, clickable selection).
apps/web/src/App.tsx	Enables viewing a profile by name in direct/native mode by fetching profile JSON and building a synthetic HistoryEntry.

[Copilot]

The comment says "Try cache first, then fall back to fetching the full profile list", but the code never falls back if /api/profile/:name doesn't return an id. In that case profileId remains the name and /api/machine/profile/${profileId}/json will likely fail (producing a HistoryEntry with null profile_json). Add the intended fallback (e.g. fetch /api/machine/profiles or /api/v1/profile/list and resolve id by name), or early-return when the id can't be resolved.

[hessius]

Already addressed. The fallback to /api/v1/profile/list is present (lines 830–840). When the cache doesn't resolve an ID (profileId === profileName), it fetches the full profile list from the machine and resolves by name.

[Copilot]

This Card is always rendered as an interactive control (role="button", tabIndex=0, aria-label, pointer cursor) even when onUseProfile is undefined, in which case it becomes a focusable element that does nothing. Make the interactivity conditional (only add onClick/keyboard handlers/role/tabIndex/aria-label/cursor-pointer when onUseProfile is provided) to avoid confusing keyboard/screen-reader users.

[hessius]

Already handled in the current code. The Card's interactive props (role, tabIndex, aria-label, onClick, onKeyDown, and cursor-pointer) are conditionally spread via {...(onUseProfile ? { ...interactiveProps } : {})} — they are only applied when onUseProfile is provided.

[Copilot]

Similar to ProfileRecommendations, this Card is always focusable/keyboard-clickable even when onSelectProfile is undefined. Either make onSelectProfile required here, or conditionally add role/tabIndex/handlers/aria-label only when a selection callback is present.

[hessius]

Already addressed — same conditional spread pattern as ProfileRecommendations. The Card only gets interactive attributes when onSelectProfile is provided.

[Copilot]

The header docs for useGlobalSoundDelegation still say data-sound "back"/"close" map to notify, but the implementation now plays tiks.click() for those cases. Update the documentation block to match the new behavior (or switch back to notify if that's what was intended).

[hessius]

Fixed — updated the file-level JSDoc to say "back", "close" → click to match the actual tiks.click() implementation. The function-level JSDoc was already correct.

[Copilot]

New preset tags like "Pressure-controlled" / "Flow-controlled" / "Mixed-controlled" are added in tags.ts, but buildUserFingerprint() only maps "pressure" and "flow" to control-mode techniques. As a result, selecting these new technique tags in the UI won't influence control-mode scoring in getRecommendations(). Add mappings for the new labels (and/or normalize tags up-front) so user-selected technique tags affect the synthetic fingerprint as intended.

[hessius]

Fixed. The tag label mappings were already present in tagToTechnique, but the controlMode assignment was missing the mixed case. Added else if (techniqueTags.has('mixed-profile')) controlMode = 'mixed' so the Mixed-controlled tag now correctly influences control-mode scoring.

[Copilot]

Tag similarity uses candFp.techniqueTags directly (e.g. "pressure-profile"/"flow-profile" internal tokens) which won't match the new user-facing preset labels (e.g. "Pressure-controlled") or temperature-range labels. Consider normalizing candidate structural features into the same vocabulary as PRESET_TAGS (e.g. add ${controlMode}-controlled and temperatureRange(temp) to allCandTags, and/or map internal technique tags to user-facing labels) so tag-based recommendations actually respond to those selections.

Suggested change

	// Merge structural technique tags into candidate tags for broader matching
	const allCandTags = new Set([...candTags, ...candFp.techniqueTags])
	if (userLower.size > 0) {
	const tagSim = jaccard(userLower, allCandTags)
	const tagPts = tagSim * 25
	score += tagPts
	const overlap: string[] = []
	for (const t of userLower) {
	if (allCandTags.has(t)) overlap.push(t)
	}
	if (overlap.length > 0) {
	// Filter out already-reported technique tags
	const userTechTags = userFingerprint?.techniqueTags ?? new Set<string>()
	const techniqueTagMap = new Map<string, string>([
	['pressure-profile', 'pressure-controlled'],
	['flow-profile', 'flow-controlled'],
	])
	const normalizedTechniqueTags = [...candFp.techniqueTags].map(tag =>
	(techniqueTagMap.get(tag.toLowerCase()) ?? tag).toLowerCase(),
	)
	const normalizedCandTags = [...candTags].map(tag => tag.toLowerCase())
	const derivedCandTags = new Set<string>([
	...normalizedCandTags,
	...normalizedTechniqueTags,
	])
	if (candFp.controlMode) {
	derivedCandTags.add(`${candFp.controlMode.toLowerCase()}-controlled`)
	}
	if (candTemp != null) {
	derivedCandTags.add(temperatureRange(candTemp).toLowerCase())
	}
	if (userLower.size > 0) {
	const tagSim = jaccard(userLower, derivedCandTags)
	const tagPts = tagSim * 25
	score += tagPts
	const overlap: string[] = []
	for (const t of userLower) {
	if (derivedCandTags.has(t)) overlap.push(t)
	}
	if (overlap.length > 0) {
	// Filter out already-reported technique tags
	const userTechTags = new Set(
	[...(userFingerprint?.techniqueTags ?? new Set<string>())].map(tag =>
	(techniqueTagMap.get(tag.toLowerCase()) ?? tag).toLowerCase(),
	),
	)

[hessius]

Already addressed. The scoring function normalizes internal technique tags to user-facing labels via techniqueToLabel (lines 149–156), and adds derived ${controlMode}-controlled and temperature-range tags to allCandTags (lines 157–168).

[Copilot]

limit is parsed from FormData without validation. If the client sends a non-numeric or negative value, parseInt() can yield NaN/negative and slice(0, limit) can behave unexpectedly (e.g. negative limit returns all-but-last). Clamp to a sane positive integer (and optionally a max) before passing to the scoring functions.

Suggested change

	let limit = 10
	const body = init?.body
	if (body instanceof FormData) {
	profileName = body.get('profile_name')?.toString() ?? ''
	limit = parseInt(body.get('limit')?.toString() ?? '10', 10)
	const DEFAULT_LIMIT = 10
	const MIN_LIMIT = 1
	const MAX_LIMIT = 100
	let limit = DEFAULT_LIMIT
	const body = init?.body
	if (body instanceof FormData) {
	profileName = body.get('profile_name')?.toString() ?? ''
	const parsedLimit = parseInt(body.get('limit')?.toString() ?? `${DEFAULT_LIMIT}`, 10)
	if (Number.isFinite(parsedLimit)) {
	limit = Math.min(MAX_LIMIT, Math.max(MIN_LIMIT, parsedLimit))
	}

[hessius]

Already addressed. Both endpoints validate/clamp limit with Number.isFinite(parsed) guard and Math.min(100, Math.max(1, parsed)), defaulting to 10 or 5 when parsing fails.

[Copilot]

Both recommendation endpoints fetch /api/v1/profile/list on every request. This can get chatty because the UI debounces but still refetches on each tag change. Since this interceptor already maintains a profile list cache (localStorage + _profileCache), consider reusing it and/or adding a short TTL in-memory cache for the full list used by the scorer to reduce repeated machine calls.

[hessius]

Already addressed — a short-lived in-memory cache (_getCachedProfileList() with 30-second TTL) was added so both endpoints share cached data and avoid repeated machine calls on rapid tag changes.

[hessius]

Addressed all 8 review findings in commit 632def7:

1. App.tsx fallback — Added fallback to fetch /api/v1/profile/list and resolve profile ID by name when cache miss occurs. Now handles both cache-hit and cache-miss paths.

2. ProfileRecommendations conditional interactivity — Card role, tabIndex, keyboard handlers, and aria-label are now only applied when onUseProfile callback is provided. No interactive ARIA attributes when non-clickable.

3. FindSimilarOverlay conditional interactivity — Same treatment applied. Interactive attributes conditional on onSelectProfile being provided.

4. useSoundEffects docs — Updated header docs: back/close → click() (was documented as notify but intentionally changed per user feedback to match forward navigation sound).

5. buildUserFingerprint mappings — Added pressure-controlled, flow-controlled, mixed-controlled → internal technique tag mappings so PRESET_TAGS selections properly influence scoring.

6. Tag vocabulary normalization — Internal technique tags (pressure-profile, flow-profile, etc.) are now normalized to user-facing labels before Jaccard comparison. Also added derived control-mode and temperature-range tags to candidate tag set for broader matching.

7. Limit validation — Both find-similar and recommend endpoints now validate/clamp limit to [1, 100] with Number.isFinite() guard.

8. Profile list caching — Added 30-second TTL in-memory cache via _getCachedProfileList(). Both recommendation endpoints now use this cached helper instead of fetching on every request.