Let a theme declare its route patterns

[hta218]

Part of #518 — the SDK half.

What

Studio resolves a page's preview URL from a hardcoded Shopify convention, so a theme that routes differently cannot be navigated from the page selector. Forward is the first such theme: /shop/:handle for collections, /journal/:handle for articles.

This adds the shared contract a theme uses to declare its own routes:

• ThemeRoutes — Partial<Record<ThemeRoutePageType, string>>, a map of page type to URL pattern. A theme declares only what differs; consumers fall back to today's Shopify convention for every key left out, so Hydrogen themes are unaffected.
• ThemeRoutePageType — Exclude<PageType, '*' | 'CUSTOM'>. * matches every page type rather than naming one, and CUSTOM pages carry their own full path, so neither can be given a pattern.
• resolveThemeRoute(pattern, params) — expands one pattern, returning null when the pattern is not an absolute path or a :param has no value, so a caller falls back to its default instead of navigating to a literal /journal/:handle.

Patterns rather than prefixes, as the issue argues: Shopify addresses an article as /blogs/:blog/:article and Forward as /journal/:article. A prefix can express journal but cannot drop the blog segment.

Both @weaverse/hydrogen and @weaverse/next already re-export the whole @weaverse/schema surface, so resolveThemeRoute reaches Builder through @weaverse/hydrogen with no extra wiring — visible in the runtime-exports.api.md diff.

What is deliberately not here

routes?: ThemeRoutes on HydrogenThemeSchema / WeaverseNextThemeSchema. I wrote it, then backed it out: internal @weaverse/* deps resolve through the public npm registry rather than as workspace links (.npmrc, commit 73b71ba7), and neither package's tsconfig maps @weaverse/schema to local source. Both fail to compile against a ThemeRoutes that is not published yet:

src/types.ts(35,3): error TS2305: Module '"@weaverse/schema"' has no exported member 'ThemeRoutes'.

So that field lands in a follow-up once @weaverse/schema ships this export. Nothing about the theme-side payload is blocked in the meantime — loadThemeSettings already spreads the whole theme schema into the design-mode payload (weaverse-client.ts:772), so a theme that sets routes today reaches Studio with it; the follow-up only adds type safety for theme authors.

Builder consumption. getDefaultPagePrefix and its three call sites live in Weaverse/builder and change separately, as the issue notes.

Open questions from the issue

I asked Codex to review the proposal first, but the connector is not configured for this repo, so these are my calls and worth a second opinion:

• Key set. ThemeRoutePageType currently admits every non-*, non-CUSTOM page type, including INDEX, BLOG, ALL_PRODUCTS, and COLLECTION_LIST. That is wider than the four keys the issue sketches. Wider seemed right — a theme that renames /collections needs COLLECTION_LIST too — but it does let a theme declare a pattern for a page type Studio never resolves by handle.
• Partial maps. A theme declaring only COLLECTION gets Shopify defaults for everything else, silently. The alternative is to reject a partial map, which seems worse for the clone-a-starter case this is meant to serve.
• Grammar. Static segments plus :param only — no optional segments, no wildcards. That covers both shapes in the issue; anything more is speculative until a theme needs it.

Verification

• turbo run typecheck --force — 6/6 pass
• pnpm run test — 8/8 tasks, @weaverse/schema 72 tests (7 new)
• biome check . — 147 files, clean

Note: commits used --no-verify; the pnpm wrapper on this machine cannot fetch its engine, which breaks the lefthook check hook. The gates above ran through a working pnpm shim.

🤖 Generated with Claude Code

---

Recreated from Weaverse/weaverse-sdk#532, which was auto-closed when its head branch was removed during the repository rename. Original discussion is on that PR.

[claude]

Claude finished @hta218's task in 1m 29s —— View job

---

Claude finished the review

Tasks

• Gather context (PR description, changed files)
• Read changed files (theme-routes.ts, theme-routes.test.ts, index.ts, API reports)
• Review diff against origin/main
• Check adherence to repo conventions (CLAUDE.md, SDD)
• Post review feedback

Review

This is a clean, well-scoped addition. A few notes, none blocking:

packages/schema/src/theme-routes.ts

• resolveThemeRoute (lines 33–56) is correct and matches its documented contract: rejects non-absolute patterns, rejects missing params, and encodes values. Good use of encodeURIComponent — verified against the "not URL-safe" test case (summer/sale → summer%2Fsale).
• Minor edge case: the missing-value check uses if (!value) (line 49), which treats an empty string '' the same as undefined. Per the type signature (Record<string, string | undefined>), a caller could legitimately pass '' for a param and get null back instead of a route with an empty segment. In practice Shopify handles/params are never empty strings, so this is unlikely to matter, but value === undefined would be more precise if you want the behavior to exactly match the JSDoc ("a :param in it has no value").
• The PARAM_SEGMENT regex (^:([a-zA-Z][a-zA-Z0-9_]*)$) only allows a :param to be a whole segment (e.g. rejects :blog-:article or prefix:param), which matches the "static segments plus :param only" grammar described in the PR body. Good.

packages/schema/src/index.ts

• Exports (ThemeRoutePageType, ThemeRoutes, resolveThemeRoute) are wired correctly and alphabetized consistently with the rest of the file.

Tests (packages/schema/test/theme-routes.test.ts)

• Good coverage of the meaningful branches: full substitution, pattern-narrower-than-params (the Forward /journal/:handle case), missing param, relative pattern, encoding, static-only pattern, and a compile-time check (expectTypeOf/@ts-expect-error) that CUSTOM and * can't be keyed. This follows the AAA structure and naming convention from AGENTS.md.
• No test exercises the empty-string-param edge case mentioned above — worth adding if you decide the !value behavior is intentional, so it's documented as a spec rather than an accident.

API reports

• The runtime-exports.api.md diff confirms resolveThemeRoute is re-exported through @weaverse/hydrogen and @weaverse/next (three insertions, one per package surface), matching the PR's claim that Builder reaches it with no extra wiring.
• schema.api.md additions (ThemeRoutePageType, ThemeRoutes, resolveThemeRoute) look consistent with the source.

Scope / conventions

• The PR correctly defers routes?: ThemeRoutes on the Hydrogen/Next theme schemas to a follow-up, with a concrete reason (unpublished type, npm-registry-resolved internal deps). That's a reasonable call given @weaverse/* packages aren't linked as workspace deps here.
• No SDD spec folder (.specs/) was added for this change. Given AGENTS.md says "All features MUST have a spec folder," this might be expected to exist — worth checking whether one was intended to accompany this PR (possibly tracked under the parent issue Let a theme declare its route patterns instead of assuming Shopify conventions #518 instead, since this PR describes itself as "the SDK half").

Not verified: I was not able to run pnpm run test, pnpm run typecheck, or biome check . in this sandbox (shell command execution required approval that wasn't available in this context). The PR description states these were run and passed locally (72 schema tests, 7 new). Static review of the diff shows nothing that would be expected to fail typecheck or lint (single quotes, no semicolons, let usage, proper type-only imports).