# Tara search and launch · source discovery · 8 September 2026

The [web search delivery](v1-tara-web-search.md) now teaches the local component
and its route boundary. The remaining independent consumers below are still
required. This historical discovery prepared the
[full V1 program](v1-completion.md), alongside the
[catalog guide](v1-tara-practice-catalog.md). This discovery itself is not
browser acceptance. Primary source pin:
`1ceae52c7896a59ac74a4429d410f3218f0b91c6`; current implementation baseline:
`5532d1513abcccb25a181c9c7a4e187a8b936536`.

## The actual Oshun web search path

Reviewed the complete 1,536-line
`apps/oshun/web/src/components/domains/tara/TaraSearchEngine.tsx`, its thin
`apps/oshun/web/src/app/domains/tara/search/page.tsx` route, the complete
157-line `apps/oshun/web/e2e/tara-scoped-search.spec.ts` and its customer
walkthrough. The component uses its own inline `SIMULATED_CONTENT` array and
`TRENDING_SEARCHES` constant. It does not import the canonical adapter or issue
a search request. A polished source-component capture must identify this as
local example content; displayed ratings, plays, followers and trending counts
are authored fixture metadata, not measured activity.

The local array contains twelve meditations, six courses, six teachers and four
collections. Search controls, matching, grouping, history and routing are real
component code over those inputs. Showing the UI can teach these mechanisms
without representing the content as a populated live service.

## Query processing and display

The component has separate raw and debounced query states. A nonempty trimmed
query sets searching true; a 250-millisecond timer copies the trimmed value to
debouncedQuery and clears searching. A later edit cancels the previous timer.
Empty input clears the debounced value and searching state. Enter records the
trimmed raw query in recents; it does not bypass the debounce. Loading shows a
spinner and four shimmer rows; the component has no failed-network branch.

Query expansion begins with lowercased whitespace-separated words. For each
original word, matching a synonym key or a member of that key's synonym list
adds the key and every synonym to a Set. This is one pass over the original
words, not recursive expansion of all newly added terms. Matching uses substring
checks and adds scores for each expanded term found in each field: title +10,
subtitle +5, snippet +3 and category +7. A record with zero matching score is
excluded before ratings or popularity are added. Matching records may receive
their rating, log10(playCount) and log10(followerCount) as additional score. The
list is sorted descending, then grouped into the fixed meditation, course,
teacher and collection section order. Ranking survives within a section; section
order does not represent a global ranking across all types.

Highlights use original query terms of at least two characters, with regular
expression metacharacters escaped. They do not mark every expanded synonym.
Consequently a valid synonym result can have no visible highlight. One-character
terms may match and score without a highlighted span. The synonym badge tests
whether expansion increased the number of terms.

Spelling suggestions use the first original word found in a fixed correction map
and a fixed confidence of 0.85. The suggestion lowercases the query and replaces
the first occurrence. It is shown independently of whether results already
exist; it is applied only when selected. Some dictionary entries map a word to
itself, so the label alone does not prove that a correction changed the query.
The empty-result view repeats an available suggestion. The AlertCircle icon
belongs to the suggestion, not a search failure.

## History and controls

The storage key is `tara-recent-searches`, separate from shell search history.
The load helper catches access and parse errors, but casts parsed JSON to a
string array without checking its runtime shape. Writes serialize at most ten
entries and catch storage errors. A current mounted state change can therefore
succeed while persistence fails. This requires a source-case exercise before
teaching any malformed-storage or next-load behavior.

Typing alone does not add a recent. Enter, selecting a recent or trending query,
applying a spelling suggestion and clicking a result do. A recent is moved to
the front through exact-string deduplication, so casing differences remain
distinct. Clear search clears the input and refocuses it; Clear all clears
recent state/storage. Removing a recent stops propagation and removes that
specific string. Query and history are not encoded into this route's URL by the
component.

The source has reduced-motion rules for the declared animated rows, highlights
and skeletons. Its input is identified by placeholder text and data hooks; do
not infer full screen-reader acceptance from those hooks. The source styles
contain fade and shimmer keyframes, not the walkthrough's named highlight-pulse
animation. This discrepancy should be stated accurately in the next guide.

## Result routing and owning destinations

The route calls `getTaraSearchResultHref` and only pushes a truthy result. The
helper returns a course route for IDs matching exactly `crs-` plus three digits,
a teacher route for `tch-` plus three digits, and an encoded collection query
parameter. Meditation results return null. Their row handler still records a
recent and invokes the callback, but the owning route does not navigate. A row,
arrow icon, score or Open accessible name does not establish a player target.

Read all three destination route wrappers. Course and teacher IDs pass through
Next route parameters to TaraCourseDetailPage and TaraTeacherProfilePage.
Collection selection is read through useBrowserSearchParams and passed as
initialCollectionId to TaraCollectionsBrowserPage. Reviewed the complete alias
resolver and browser selection state: col-001 maps to tara-coll-001, col-002 to
002, col-003 to 008 and col-004 to 007. The resolver accepts direct collection
IDs, searches the local collection array and returns null for unknown values.
The browser updates selection when the initial prop changes. Other collection,
program, course and teacher behavior is not fully reviewed by this route trace.

Existing focused E2E source checks idle/recent controls, settled debounce,
synonyms, spelling application, empty results and reduced-motion observations.
It also checks the meditation row's empty href and actual course, teacher and
collection destination pages. Those historical tests were read, not rerun in the
catalog delivery. A new source-component fixture can capture representative
states and exercise exact debounce/history/routing behavior; it must retain its
host seams and distinguish callback verification from actual Next navigation.
The existing application E2E remains the owning full-route avenue when a usable
application test host is available.

## Distinct search and recommendation implementations

Earlier complete reads of domain-tara canonical-adapter.ts, domain-adapter.ts,
adapter.ts, client.ts and the BFF Tara route/read-adapter wrapper establish a
separate recommendation-backed search path. It uses whitespace tokens with AND
substring filtering over title/summary/tags and optional intensity/duration
filters. Its result pool, ordering and optional user-specific sources are not
the local web engine's synonym/scoring implementation. Course and favorite
sources require configured searchUserId; the BFF read-adapter wrapper currently
supplies only apiAdapter. Saved-item mutation is a separate add/remove API path.
BFF authentication and server calls must be explained with their actual caller,
not attached to the local web component by a similar name.

Additional discovered implementations still require complete review:
`apps/tara/web/src/app/[locale]/(app)/search/page.tsx`,
`apps/tara/mobile/app/search.tsx`, `apps/tara/api/src/routes/search/`,
`libs/tara/content/src/search/` and
`libs/oshun/domain-tara/src/favorites-sync.ts`. Only initial portions of the
standalone web and content-library engine were inspected. The content-library
index/cache/filter machinery cannot be called this component's backend without
an actual import/call chain.

## Proposed teaching shape

Visual thesis: show the real search surface using its explicitly labeled local
example data, then unfold a query into matching, grouped results, history and a
supported destination. Use query-state transitions, a small score calculation, a
routing decision and a storage/readback case rather than a feature list.

Content plan: orient with one query and a continuous source capture; explain
idle/loading/results, expansion, weighted matching, grouping and highlights;
show spelling and empty results; follow recent-history events; trace result kind
to supported route and close with the actual destination. The distinct
canonical/BFF recommendation and saved-item path needs a linked guide of its own
if combining it would obscure these two implementations. Full taxonomy
selection, native callers, companions, mentors and workbenches remain required.

Interaction thesis: source reveals and selectable native diagrams retain all
meaning in HTML/PDF; a product crop can pan without changing slides. Use the
existing reduced-motion behavior and avoid ornamental animation.
