@wix/agent-skills 1.19.2 → 1.20.0

package/skills/wix-vibe-headless/references/blog/INSTRUCTIONS.md

@@ -39,12 +39,29 @@ real fallback — a runtime error, or a field the snippets don't cover (see "Fal
 end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
 `references/blog/app/` → `src/`.)
 
+**Their `Link`/`useParams` imports come from `@/lib/nav`**, so the same sources run on either
+template. That adapter is installed at `src/lib/nav.js` with the rest of the deployed tree — use
+the file that is there, and on TanStack check it first ([which template?](../_shared/routing.md)).
+Import from `@/lib/nav` in the pages you write too, and they stay portable the same way.
+
+
 
 ## STEP 2 — Theme
 Use the existing Base44 theme in `src/index.css` so your pages and the shipped components
 share the same colors and typography.
 
 ## STEP 3 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+
+> **The template decides this step, and `src/routes/__root.jsx` is the question to ask first.**
+> Present → TanStack Start, which mounts these pages as route files at the end of this step; absent
+> → React Router, which the wiring below is written for. Ask in that order: an `src/App.jsx` can
+> exist on a TanStack app because an agent created one, and `__root.jsx` is never there by mistake.
+> The installed `src/lib/nav.js` defaults to the React Router adapter, so on TanStack swap it:
+> [both patterns](../_shared/routing.md).
+>
+> **Import `Link`, `useParams` and friends from `@/lib/nav` in the pages you write too** — same
+> names as the router exports, and nothing you write is pinned to one template.
+
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
 `App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
 replace it.
@@ -108,6 +125,33 @@ function Layout() {
 </TaxonomyProvider>
 ```
 
+
+### TanStack Start template — the same pages, mounted as files
+
+Chrome (header, footer, the fixed banner region described above) goes in `src/routes/__root.jsx`
+around its `<Outlet/>`, and any provider this vertical asks for wraps that `<Outlet/>` once. Each
+route is a two-line file; shipped pages stay in `src/pages/` untouched.
+
+| route | file | component |
+|---|---|---|
+| `/` | `src/routes/index.jsx` | `Home` |
+| `/blog` | `src/routes/blog.index.jsx` | `Blog` |
+| `/blog/:slug` | `src/routes/blog.$slug.jsx` | `PostDetail` |
+| `/blog/category/:slug` | `src/routes/blog.category.$slug.jsx` | `CategoryPage` |
+| `/blog/tag/:slug` | `src/routes/blog.tag.$slug.jsx` | `TagPage` |
+
+```jsx
+// src/routes/blog.index.jsx
+import { createFileRoute } from "@tanstack/react-router";
+import Blog from "@/pages/Blog";
+
+export const Route = createFileRoute("/blog")({ component: Blog });
+```
+
+Path params are `$name` in both the filename and the route path; `useParams()` from `@/lib/nav`
+reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
+[`../_shared/routing.md`](../_shared/routing.md).
+
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** and a **`Footer`** — the two you drop into the `Layout`
 (STEP 3) so they wrap every route — plus the overall brand story, styled with the same base44

package/skills/wix-vibe-headless/references/blog/app/components/PostCard.jsx

@@ -1,7 +1,7 @@
 // Feed tile. Styled with base44 design tokens (shadcn Tailwind classes) — re-skin via those tokens, not this
 // JSX. The cover-image path (post.media.wixMedia.image.url) and the text-only fallback are
 // load-bearing: never substitute a stock/placeholder image. Routes to the detail page by slug.
-import { Link } from "react-router-dom";
+import { Link } from "@/lib/nav";
 
 function coverImage(post) {
   const url = post?.media?.wixMedia?.image?.url;         // ready-to-use https url; //-fix is defensive

package/skills/wix-vibe-headless/references/blog/app/components/PostChips.jsx

@@ -1,7 +1,7 @@
 // Category + tag chips for a post. Resolves the post's categoryIds/tagIds against the SHARED
 // taxonomy maps (fetched once by TaxonomyProvider — never re-query here), displays each by .label
 // (NOT .name), and routes by .slug. Styled with base44 design tokens (shadcn Tailwind classes).
-import { Link } from "react-router-dom";
+import { Link } from "@/lib/nav";
 import { useTaxonomy } from "@/context/TaxonomyContext";
 
 const chip = "inline-flex items-center py-1 px-2.5 text-[12px] no-underline text-foreground bg-card border border-border rounded-full";

package/skills/wix-vibe-headless/references/blog/app/pages/CategoryPage.jsx

@@ -3,7 +3,7 @@
 // feed, so paging is identical). Displays the category by .label; cover from category.coverImage.url
 // (a DIFFERENT path from the post cover). Styled with base44 design tokens (shadcn Tailwind classes).
 import { useEffect, useState } from "react";
-import { useParams } from "react-router-dom";
+import { useParams } from "@/lib/nav";
 import { getCategoryBySlug, queryPostsByCategory } from "@/rest/wix-blog";
 import PostGrid from "@/components/PostGrid";
 

package/skills/wix-vibe-headless/references/blog/app/pages/PostDetail.jsx

@@ -2,7 +2,7 @@
 // category/tag chips, and the plain-text body as paragraphs. For a faithful render of embeds/images/
 // formatting, render `d.post.richContent` with a Ricos renderer (see INSTRUCTIONS "Extending").
 // Styled with base44 design tokens (shadcn Tailwind classes).
-import { useParams } from "react-router-dom";
+import { useParams } from "@/lib/nav";
 import { usePostDetail } from "@/hooks/usePostDetail";
 import PostChips from "@/components/PostChips";
 

package/skills/wix-vibe-headless/references/blog/app/pages/TagPage.jsx

@@ -2,7 +2,7 @@
 // tag's posts via queryPostsByTag (same { posts, nextCursor } shape as the feed). Displays the tag by
 // .label (per-tag count is publishedPostCount). Styled with base44 design tokens (shadcn Tailwind classes).
 import { useEffect, useState } from "react";
-import { useParams } from "react-router-dom";
+import { useParams } from "@/lib/nav";
 import { getTagBySlug, queryPostsByTag } from "@/rest/wix-blog";
 import PostGrid from "@/components/PostGrid";
 

package/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md

@@ -50,12 +50,29 @@ on a real fallback — a runtime error, or a field the snippets don't cover (see
 the end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
 `references/bookings/app/` → `src/`.)
 
+**Their `Link`/`useParams` imports come from `@/lib/nav`**, so the same sources run on either
+template. That adapter is installed at `src/lib/nav.js` with the rest of the deployed tree — use
+the file that is there, and on TanStack check it first ([which template?](../_shared/routing.md)).
+Import from `@/lib/nav` in the pages you write too, and they stay portable the same way.
+
+
 
 ## STEP 2 — Theme
 Use the existing Base44 theme in `src/index.css` so your pages and the shipped components
 share the same colors and typography.
 
 ## STEP 3 — Wire routes (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+
+> **The template decides this step, and `src/routes/__root.jsx` is the question to ask first.**
+> Present → TanStack Start, which mounts these pages as route files at the end of this step; absent
+> → React Router, which the wiring below is written for. Ask in that order: an `src/App.jsx` can
+> exist on a TanStack app because an agent created one, and `__root.jsx` is never there by mistake.
+> The installed `src/lib/nav.js` defaults to the React Router adapter, so on TanStack swap it:
+> [both patterns](../_shared/routing.md).
+>
+> **Import `Link`, `useParams` and friends from `@/lib/nav` in the pages you write too** — same
+> names as the router exports, and nothing you write is pinned to one template.
+
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
 `App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
 replace it. Bookings needs **no cross-page provider** (there's no cart — each booking completes on
@@ -111,6 +128,31 @@ function Layout() {
 </Routes>
 ```
 
+
+### TanStack Start template — the same pages, mounted as files
+
+Chrome (header, footer, the fixed banner region described above) goes in `src/routes/__root.jsx`
+around its `<Outlet/>`, and any provider this vertical asks for wraps that `<Outlet/>` once. Each
+route is a two-line file; shipped pages stay in `src/pages/` untouched.
+
+| route | file | component |
+|---|---|---|
+| `/` | `src/routes/index.jsx` | `Home` |
+| `/services` | `src/routes/services.jsx` | `Services` |
+| `/service/:serviceId` | `src/routes/service.$serviceId.jsx` | `ServiceDetail` |
+
+```jsx
+// src/routes/services.jsx
+import { createFileRoute } from "@tanstack/react-router";
+import Services from "@/pages/Services";
+
+export const Route = createFileRoute("/services")({ component: Services });
+```
+
+Path params are `$name` in both the filename and the route path; `useParams()` from `@/lib/nav`
+reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
+[`../_shared/routing.md`](../_shared/routing.md).
+
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** and a **`Footer`** — the two you drop into the
 `Layout` (STEP 3) so they wrap every route — plus the overall brand story, styled with the same

package/skills/wix-vibe-headless/references/bookings/app/components/ServiceCard.jsx

@@ -3,7 +3,7 @@
 // (src/index.css :root/.dark), not this JSX. Load-bearing: the image goes through mediaUrl() (Wix
 // media can be a bare handle), the link uses `service.id`, and every price/duration/capacity label
 // comes from lib/serviceFacts.js so the card and the detail page can't disagree.
-import { Link } from "react-router-dom";
+import { Link } from "@/lib/nav";
 import { mediaUrl } from "@/rest/wix-bookings-services";
 import { serviceCapacityLabel, serviceDuration, servicePriceLabel } from "@/lib/serviceFacts";
 

package/skills/wix-vibe-headless/references/bookings/app/pages/ServiceDetail.jsx

@@ -2,7 +2,7 @@
 // pick a slot, enter details, book → hosted checkout. Two columns: what you're booking on the left,
 // the booking panel on the right, sticky on desktop so the times stay in reach while reading.
 // Styled with base44 design tokens (shadcn Tailwind classes).
-import { useParams } from "react-router-dom";
+import { useParams } from "@/lib/nav";
 import { useServiceDetail } from "@/hooks/useServiceDetail";
 import { mediaUrl } from "@/rest/wix-bookings-services";
 import SlotPicker from "@/components/SlotPicker";

package/skills/wix-vibe-headless/references/events/INSTRUCTIONS.md

@@ -46,12 +46,29 @@ real fallback — a runtime error, or a field the snippets don't cover (see "Fal
 end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
 `references/events/app/` → `src/`.)
 
+**Their `Link`/`useParams` imports come from `@/lib/nav`**, so the same sources run on either
+template. That adapter is installed at `src/lib/nav.js` with the rest of the deployed tree — use
+the file that is there, and on TanStack check it first ([which template?](../_shared/routing.md)).
+Import from `@/lib/nav` in the pages you write too, and they stay portable the same way.
+
+
 
 ## STEP 2 — Theme
 Use the existing Base44 theme in `src/index.css` so your pages and the shipped components
 share the same colors and typography.
 
 ## STEP 3 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+
+> **The template decides this step, and `src/routes/__root.jsx` is the question to ask first.**
+> Present → TanStack Start, which mounts these pages as route files at the end of this step; absent
+> → React Router, which the wiring below is written for. Ask in that order: an `src/App.jsx` can
+> exist on a TanStack app because an agent created one, and `__root.jsx` is never there by mistake.
+> The installed `src/lib/nav.js` defaults to the React Router adapter, so on TanStack swap it:
+> [both patterns](../_shared/routing.md).
+>
+> **Import `Link`, `useParams` and friends from `@/lib/nav` in the pages you write too** — same
+> names as the router exports, and nothing you write is pinned to one template.
+
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
 `App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
 replace it. (Events needs no cross-page provider — there's no cart; the RSVP/ticketing state is local
@@ -107,6 +124,31 @@ function Layout() {
 </Routes>
 ```
 
+
+### TanStack Start template — the same pages, mounted as files
+
+Chrome (header, footer, the fixed banner region described above) goes in `src/routes/__root.jsx`
+around its `<Outlet/>`, and any provider this vertical asks for wraps that `<Outlet/>` once. Each
+route is a two-line file; shipped pages stay in `src/pages/` untouched.
+
+| route | file | component |
+|---|---|---|
+| `/` | `src/routes/index.jsx` | `Home` |
+| `/events` | `src/routes/events.index.jsx` | `Events` |
+| `/events/:slug` | `src/routes/events.$slug.jsx` | `EventDetail` |
+
+```jsx
+// src/routes/events.index.jsx
+import { createFileRoute } from "@tanstack/react-router";
+import Events from "@/pages/Events";
+
+export const Route = createFileRoute("/events")({ component: Events });
+```
+
+Path params are `$name` in both the filename and the route path; `useParams()` from `@/lib/nav`
+reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
+[`../_shared/routing.md`](../_shared/routing.md).
+
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** and a **`Footer`** — the two you drop into the `Layout`
 (STEP 3) so they wrap every route — plus the overall brand story, styled with the same base44

package/skills/wix-vibe-headless/references/events/app/components/EventCard.jsx

@@ -4,7 +4,7 @@
 // formattedValue } — render formattedValue, NEVER the raw object (React "objects are not valid as a
 // child" crash). This is a different shape from the ticket-definition price (pricing.fixedPrice.amount)
 // used in the picker.
-import { Link } from "react-router-dom";
+import { Link } from "@/lib/nav";
 
 export default function EventCard({ event }) {
   const when = event.dateAndTimeSettings?.formatted?.dateAndTime;

package/skills/wix-vibe-headless/references/events/app/pages/EventDetail.jsx

@@ -4,7 +4,7 @@
 // shortDescription is a PLAIN string (safe to render). event.description is Ricos rich content
 // { nodes: [...] } — NOT a string; to show the full body render it with @wix/ricos or walk `nodes`.
 // NEVER call string methods (.slice/.substring/.split) on event.description — that crashes the page.
-import { useParams } from "react-router-dom";
+import { useParams } from "@/lib/nav";
 import { useEventDetail } from "@/hooks/useEventDetail";
 import EventRegistration from "@/components/EventRegistration";
 

package/skills/wix-vibe-headless/references/members/INSTRUCTIONS.md

@@ -65,6 +65,12 @@ fallback — a runtime error, or a field the snippets don't cover (see "Fallback
 (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
 `references/members/app/` → `src/`.)
 
+**Their `Link`/`useParams` imports come from `@/lib/nav`**, so the same sources run on either
+template. That adapter is installed at `src/lib/nav.js` with the rest of the deployed tree — use
+the file that is there, and on TanStack check it first ([which template?](../_shared/routing.md)).
+Import from `@/lib/nav` in the pages you write too, and they stay portable the same way.
+
+
 > **⚠️ Copy `wix-members-auth.js` verbatim — do NOT rewrite its internals.** The OAuth wire shapes are
 > exact and unforgiving: the `createRedirectSession` body needs the `auth.authRequest` wrapper, flat
 > PKCE fields, and `responseType`/`scope` — "simplifying" it returns **400** and login dies. Extend by
@@ -77,6 +83,17 @@ Use the existing Base44 theme in `src/index.css` so your pages and the shipped c
 share the same colors and typography.
 
 ## STEP 3 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+
+> **The template decides this step, and `src/routes/__root.jsx` is the question to ask first.**
+> Present → TanStack Start, which mounts these pages as route files at the end of this step; absent
+> → React Router, which the wiring below is written for. Ask in that order: an `src/App.jsx` can
+> exist on a TanStack app because an agent created one, and `__root.jsx` is never there by mistake.
+> The installed `src/lib/nav.js` defaults to the React Router adapter, so on TanStack swap it:
+> [both patterns](../_shared/routing.md).
+>
+> **Import `Link`, `useParams` and friends from `@/lib/nav` in the pages you write too** — same
+> names as the router exports, and nothing you write is pinned to one template.
+
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
 `App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`, the **Base44 builder
 account**) — edit it in, don't replace it. The Wix member session is separate and ships under its own
@@ -140,6 +157,31 @@ function Layout() {
 </MemberProvider>
 ```
 
+
+### TanStack Start template — the same pages, mounted as files
+
+Chrome (header, footer, the fixed banner region described above) goes in `src/routes/__root.jsx`
+around its `<Outlet/>`, and any provider this vertical asks for wraps that `<Outlet/>` once. Each
+route is a two-line file; shipped pages stay in `src/pages/` untouched.
+
+| route | file | component |
+|---|---|---|
+| `/` | `src/routes/index.jsx` | `Home` |
+| `/login` | `src/routes/login.jsx` | `Login` |
+| `/callback` | `src/routes/callback.jsx` | `Callback` |
+
+```jsx
+// src/routes/login.jsx
+import { createFileRoute } from "@tanstack/react-router";
+import Login from "@/pages/Login";
+
+export const Route = createFileRoute("/login")({ component: Login });
+```
+
+Path params are `$name` in both the filename and the route path; `useParams()` from `@/lib/nav`
+reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
+[`../_shared/routing.md`](../_shared/routing.md).
+
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** (mount `<MemberMenu/>` in it) and a **`Footer`** — the
 two you drop into the `Layout` (STEP 3) so they wrap every route — plus the overall brand story,

package/skills/wix-vibe-headless/references/members/app/components/MemberMenu.jsx

@@ -2,7 +2,7 @@
 // session state: a "Log in" link for a visitor, or the member's name + a log-out button once signed
 // in. Drop it into the Header you build (STEP 4), same as the storefront's CartButton. Pure UI reading
 // useMember + base44 design tokens (shadcn Tailwind classes) — render it as-is; don't wrap it in your own auth logic.
-import { Link } from "react-router-dom";
+import { Link } from "@/lib/nav";
 import { useMember } from "@/context/MemberContext";
 
 export default function MemberMenu() {

package/skills/wix-vibe-headless/references/members/app/components/RequireAuth.jsx

@@ -2,7 +2,7 @@
 // children only for a logged-in member, otherwise redirects to /login (carrying the attempted path so
 // login can return there). This is the gate the shipped Account page uses; reuse it for your own
 // member-only routes ("my orders", "my plans", …). Reads useMember; no styling of its own.
-import { Navigate, useLocation } from "react-router-dom";
+import { Navigate, useLocation } from "@/lib/nav";
 import { useMember } from "@/context/MemberContext";
 
 export default function RequireAuth({ children, fallback = "/login" }) {

package/skills/wix-vibe-headless/references/members/app/pages/Login.jsx

@@ -3,7 +3,7 @@
 // they came from (RequireAuth stashes it in location.state.from) or home. Social login returns via
 // /callback instead. Styled with base44 design tokens (shadcn Tailwind classes) — don't rewrite this page to add chrome
 // (the Header/Footer live in the Layout).
-import { useNavigate, useLocation } from "react-router-dom";
+import { useNavigate, useLocation } from "@/lib/nav";
 import LoginForm from "@/components/LoginForm";
 import SocialButtons from "@/components/SocialButtons";
 

package/skills/wix-vibe-headless/references/portfolio/INSTRUCTIONS.md

@@ -47,12 +47,29 @@ a real fallback — a runtime error, or a field the snippets don't cover (see "F
 end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
 `references/portfolio/app/` → `src/`.)
 
+**Their `Link`/`useParams` imports come from `@/lib/nav`**, so the same sources run on either
+template. That adapter is installed at `src/lib/nav.js` with the rest of the deployed tree — use
+the file that is there, and on TanStack check it first ([which template?](../_shared/routing.md)).
+Import from `@/lib/nav` in the pages you write too, and they stay portable the same way.
+
+
 
 ## STEP 2 — Theme
 Use the existing Base44 theme in `src/index.css` so your pages and the shipped components
 share the same colors and typography.
 
 ## STEP 3 — Wire routes (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+
+> **The template decides this step, and `src/routes/__root.jsx` is the question to ask first.**
+> Present → TanStack Start, which mounts these pages as route files at the end of this step; absent
+> → React Router, which the wiring below is written for. Ask in that order: an `src/App.jsx` can
+> exist on a TanStack app because an agent created one, and `__root.jsx` is never there by mistake.
+> The installed `src/lib/nav.js` defaults to the React Router adapter, so on TanStack swap it:
+> [both patterns](../_shared/routing.md).
+>
+> **Import `Link`, `useParams` and friends from `@/lib/nav` in the pages you write too** — same
+> names as the router exports, and nothing you write is pinned to one template.
+
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
 `App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
 replace it. Portfolio is read-only with no cross-page state, so there's **no provider to wrap** (no
@@ -110,6 +127,32 @@ function Layout() {
 </Routes>
 ```
 
+
+### TanStack Start template — the same pages, mounted as files
+
+Chrome (header, footer, the fixed banner region described above) goes in `src/routes/__root.jsx`
+around its `<Outlet/>`, and any provider this vertical asks for wraps that `<Outlet/>` once. Each
+route is a two-line file; shipped pages stay in `src/pages/` untouched.
+
+| route | file | component |
+|---|---|---|
+| `/` | `src/routes/index.jsx` | `Home` |
+| `/portfolio` | `src/routes/portfolio.jsx` | `Portfolio` |
+| `/collection/:slug` | `src/routes/collection.$slug.jsx` | `CollectionPage` |
+| `/project/:slug` | `src/routes/project.$slug.jsx` | `ProjectDetail` |
+
+```jsx
+// src/routes/portfolio.jsx
+import { createFileRoute } from "@tanstack/react-router";
+import Portfolio from "@/pages/Portfolio";
+
+export const Route = createFileRoute("/portfolio")({ component: Portfolio });
+```
+
+Path params are `$name` in both the filename and the route path; `useParams()` from `@/lib/nav`
+reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
+[`../_shared/routing.md`](../_shared/routing.md).
+
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** and a **`Footer`** — the two you drop into the `Layout`
 (STEP 3) so they wrap every route — plus the overall brand story, styled with the same base44

package/skills/wix-vibe-headless/references/portfolio/app/components/CollectionCard.jsx

@@ -1,7 +1,7 @@
 // Collection tile → links to /collection/:slug. Styled with base44 design tokens (shadcn Tailwind
 // classes) — re-skin via the app's design tokens (src/index.css :root/.dark), not this JSX. The
 // `//`-protocol image fix and the coverImage.imageInfo.url field path are load-bearing.
-import { Link } from "react-router-dom";
+import { Link } from "@/lib/nav";
 
 function coverUrl(collection) {
   const url = collection?.coverImage?.imageInfo?.url;

package/skills/wix-vibe-headless/references/portfolio/app/components/ProjectCard.jsx

@@ -2,7 +2,7 @@
 // — re-skin via the app's design tokens (src/index.css :root/.dark), not this JSX. The cover is a
 // one-of: image when present, else the video's poster / first resolution. The `//`-protocol fix and
 // these field paths are load-bearing.
-import { Link } from "react-router-dom";
+import { Link } from "@/lib/nav";
 
 function https(url) {
   return url ? (url.startsWith("//") ? `https:${url}` : url) : null;

package/skills/wix-vibe-headless/references/portfolio/app/pages/CollectionPage.jsx

@@ -1,6 +1,6 @@
 // Collection page — collection header + its project grid (paged). Thin view over
 // useCollectionProjects (all data logic lives in the hook). Styled with base44 design tokens (shadcn Tailwind classes).
-import { useParams } from "react-router-dom";
+import { useParams } from "@/lib/nav";
 import { useCollectionProjects } from "@/hooks/useCollectionProjects";
 import ProjectGrid from "@/components/ProjectGrid";
 

package/skills/wix-vibe-headless/references/portfolio/app/pages/ProjectDetail.jsx

@@ -1,7 +1,7 @@
 // Project detail — thin view over useProjectDetail (all data logic lives in the hook). Renders the
 // header, the details[] rows (text OR link), and the media gallery (each item via ProjectMedia,
 // which branches on item.type). Styled with base44 design tokens (shadcn Tailwind classes).
-import { useParams } from "react-router-dom";
+import { useParams } from "@/lib/nav";
 import { useProjectDetail } from "@/hooks/useProjectDetail";
 import ProjectMedia from "@/components/ProjectMedia";
 

package/skills/wix-vibe-headless/references/pricing-plans/INSTRUCTIONS.md

@@ -50,12 +50,29 @@ a real fallback — a runtime error, or a field the snippets don't cover (see "F
 end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
 `references/pricing-plans/app/` → `src/`.)
 
+**Their `Link`/`useParams` imports come from `@/lib/nav`**, so the same sources run on either
+template. That adapter is installed at `src/lib/nav.js` with the rest of the deployed tree — use
+the file that is there, and on TanStack check it first ([which template?](../_shared/routing.md)).
+Import from `@/lib/nav` in the pages you write too, and they stay portable the same way.
+
+
 
 ## STEP 2 — Theme
 Use the existing Base44 theme in `src/index.css` so your pages and the shipped components
 share the same colors and typography.
 
 ## STEP 3 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+
+> **The template decides this step, and `src/routes/__root.jsx` is the question to ask first.**
+> Present → TanStack Start, which mounts these pages as route files at the end of this step; absent
+> → React Router, which the wiring below is written for. Ask in that order: an `src/App.jsx` can
+> exist on a TanStack app because an agent created one, and `__root.jsx` is never there by mistake.
+> The installed `src/lib/nav.js` defaults to the React Router adapter, so on TanStack swap it:
+> [both patterns](../_shared/routing.md).
+>
+> **Import `Link`, `useParams` and friends from `@/lib/nav` in the pages you write too** — same
+> names as the router exports, and nothing you write is pinned to one template.
+
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
 `App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
 replace it. Pricing Plans needs **no** cross-page provider (checkout is a redirect, not client
@@ -113,6 +130,32 @@ function Layout() {
 </Routes>
 ```
 
+
+### TanStack Start template — the same pages, mounted as files
+
+Chrome (header, footer, the fixed banner region described above) goes in `src/routes/__root.jsx`
+around its `<Outlet/>`, and any provider this vertical asks for wraps that `<Outlet/>` once. Each
+route is a two-line file; shipped pages stay in `src/pages/` untouched.
+
+| route | file | component |
+|---|---|---|
+| `/` | `src/routes/index.jsx` | `Home` |
+| `/plans` | `src/routes/plans.index.jsx` | `Plans` |
+| `/plans/:slug` | `src/routes/plans.$slug.jsx` | `PlanDetail` |
+| `/my-plans` | `src/routes/my-plans.jsx` | `MyPlans` |
+
+```jsx
+// src/routes/plans.index.jsx
+import { createFileRoute } from "@tanstack/react-router";
+import Plans from "@/pages/Plans";
+
+export const Route = createFileRoute("/plans")({ component: Plans });
+```
+
+Path params are `$name` in both the filename and the route path; `useParams()` from `@/lib/nav`
+reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
+[`../_shared/routing.md`](../_shared/routing.md).
+
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** and a **`Footer`** — the two you drop into the
 `Layout` (STEP 3) so they wrap every route — plus the overall brand story, styled with the same

package/skills/wix-vibe-headless/references/pricing-plans/app/components/PlanCard.jsx

@@ -7,7 +7,7 @@
 // plan.image is a WixMedia object { id, width, height, altText } with NO .url — its id must be
 // resolved to a URL before it can render. Rendering plan text only here avoids that trap; see
 // INSTRUCTIONS ("Plan image") for the resolve-or-omit fallback if you want the image.
-import { Link } from "react-router-dom";
+import { Link } from "@/lib/nav";
 import PlanPrice from "./PlanPrice";
 
 export default function PlanCard({ plan, onSubscribe, featured = false }) {

package/skills/wix-vibe-headless/references/pricing-plans/app/pages/PlanDetail.jsx

@@ -2,7 +2,7 @@
 // price/billing summary, perks, terms & conditions if present, and a Subscribe button (only when
 // plan.buyable). Not-found state on a bad slug — never invent a plan. Styled with base44 design
 // tokens (shadcn Tailwind classes). termsAndConditions is plain text; render as-is.
-import { useParams } from "react-router-dom";
+import { useParams } from "@/lib/nav";
 import { usePlanDetail } from "@/hooks/usePlanDetail";
 import PlanPrice from "@/components/PlanPrice";
 

package/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md

@@ -56,6 +56,17 @@ Use the existing Base44 theme in `src/index.css` so your pages and the shipped c
 share the same colors and typography.
 
 ## STEP 3 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+
+> **The template decides this step, and `src/routes/__root.jsx` is the question to ask first.**
+> Present → TanStack Start, which mounts these pages as route files at the end of this step; absent
+> → React Router, which the wiring below is written for. Ask in that order: an `src/App.jsx` can
+> exist on a TanStack app because an agent created one, and `__root.jsx` is never there by mistake.
+> The installed `src/lib/nav.js` defaults to the React Router adapter, so on TanStack swap it:
+> [both patterns](../_shared/routing.md).
+>
+> **Import `Link`, `useParams` and friends from `@/lib/nav` in the pages you write too** — same
+> names as the router exports, and nothing you write is pinned to one template.
+
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
 `App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
 replace it.
@@ -116,6 +127,31 @@ function Layout() {
 </OrderCartProvider>
 ```
 
+
+### TanStack Start template — the same pages, mounted as files
+
+Chrome (header, footer, the fixed banner region described above) goes in `src/routes/__root.jsx`
+around its `<Outlet/>`, and any provider this vertical asks for wraps that `<Outlet/>` once. Each
+route is a two-line file; shipped pages stay in `src/pages/` untouched.
+
+| route | file | component |
+|---|---|---|
+| `/` | `src/routes/index.jsx` | `Home` |
+| `/menu` | `src/routes/menu.jsx` | `Menu` |
+| `/reservations` | `src/routes/reservations.jsx` | `Reservations` |
+
+```jsx
+// src/routes/menu.jsx
+import { createFileRoute } from "@tanstack/react-router";
+import Menu from "@/pages/Menu";
+
+export const Route = createFileRoute("/menu")({ component: Menu });
+```
+
+Path params are `$name` in both the filename and the route path; `useParams()` from `@/lib/nav`
+reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
+[`../_shared/routing.md`](../_shared/routing.md).
+
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** (mount `<OrderCartButton/>` in it) and a **`Footer`** —
 the two you drop into the `Layout` (STEP 3) so they wrap every route — plus the overall brand story,

package/skills/wix-vibe-headless/references/shared/app/lib/nav.js

@@ -0,0 +1,9 @@
+// Navigation adapter — React Router template (src/App.jsx + react-router-dom).
+// Shipped components import Link/useParams/etc from "@/lib/nav" so the same files run on either
+// Base44 template; this file is the only place the router is named.
+//
+// It rides in the deployed tree, so every install path lands it — including the ones that copy
+// `shared/app/` directly instead of running install/deploy.cjs. On the TanStack Start template
+// (src/routes/__root.jsx present) `_shared/nav/nav.tanstack.js` replaces it; deploy.cjs does that
+// swap on its own. See `_shared/routing.md`.
+export { Link, useParams, useNavigate, useLocation, Navigate } from "react-router-dom";