@hitch42/applet 0.1.1-beta.8 → 0.1.1-beta.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (167) hide show
  1. package/dist/_internal/client.js +120 -11
  2. package/dist/_internal/log-context.d.ts +34 -0
  3. package/dist/_internal/log-context.js +2 -0
  4. package/dist/_internal/server.d.ts +1 -1
  5. package/dist/_internal/server.js +112 -57
  6. package/dist/applet.js +12 -12
  7. package/dist/build-Bh_S5BUv.js +2 -0
  8. package/dist/{build-DANx9Hgg.js → build-CEfFoIZZ.js} +1 -1
  9. package/dist/{ci-5qWl7lT3.js → ci-BKw14X2h.js} +14 -13
  10. package/dist/client.d.ts +3 -3
  11. package/dist/{contract-rP_eV9PK.d.ts → contract-CsUpTBe0.d.ts} +1 -1
  12. package/dist/{deploy-MQWLG2EA.js → deploy-wGYjwXrx.js} +139 -88
  13. package/dist/{generate-BxYHdoAQ.js → generate-BEIYs17x.js} +65 -28
  14. package/dist/generate-Dox-OYt6.js +2 -0
  15. package/dist/headers-DkNr9MLJ.js +17 -0
  16. package/dist/index.d.ts +23 -22
  17. package/dist/index.js +2 -1
  18. package/dist/{init-jDEgYIXg.js → init-6oGPM46R.js} +15 -17
  19. package/dist/{load-config-BYSxDVAl.js → load-config-xEdTXs0y.js} +2 -2
  20. package/dist/log-context-zu8U9Sjm.js +73 -0
  21. package/dist/{login-C7RKmmTe.js → login-CUx3TmFQ.js} +1 -1
  22. package/dist/{logs-DgjgAxj2.js → logs-DSjuEN0Q.js} +20 -22
  23. package/dist/{manifest-DD_SGkS6.d.ts → manifest-C6_F4bL8.d.ts} +5 -1
  24. package/dist/{manifest-Bp87Uz0a.js → manifest-CJSL9GuC.js} +20 -4
  25. package/dist/{project-CbYPtpPq.js → project-BRZGd6xq.js} +199 -18
  26. package/dist/query-cache-CXmAyLv3.js +82 -0
  27. package/dist/react.d.ts +3 -2
  28. package/dist/react.js +98 -80
  29. package/dist/{schedules-dhU1yyFr.js → schedules-C8_Svr4h.js} +1 -1
  30. package/dist/server.d.ts +9 -4
  31. package/dist/server.js +29 -8
  32. package/dist/{telephony-protocol-DRgiYjqQ.d.ts → telephony-protocol-D-nf3Gca.d.ts} +15 -13
  33. package/dist/telephony.d.ts +24 -4
  34. package/dist/telephony.js +135 -16
  35. package/dist/{upload-YbRKEqR6.d.ts → upload-DKZzz5kW.d.ts} +6 -6
  36. package/dist/{variables-Bwnr7oxf.js → variables-DT5RyHdH.js} +13 -13
  37. package/dist/vite.d.ts +3 -60
  38. package/dist/vite.js +50 -15
  39. package/dist/{workflow-engine-MogejNfF.js → workflow-engine-BOTzURKM.js} +1 -7
  40. package/dist/{workspace-XVtM12ZC.js → workspace-D0dnnlxL.js} +33 -38
  41. package/package.json +13 -5
  42. package/scaffold/.agents/skills/hitch-applets/SKILL.md +30 -4
  43. package/scaffold/.agents/skills/hitch-applets/references/manifest.md +8 -0
  44. package/scaffold/.agents/skills/hitch-applets/references/markdown.md +2 -0
  45. package/scaffold/.agents/skills/hitch-applets/references/records.md +23 -1
  46. package/scaffold/.agents/skills/hitch-data/SKILL.md +2 -1
  47. package/scaffold/.agents/skills/hitch-data/references/attributes.md +7 -1
  48. package/scaffold/.agents/skills/hitch-data/references/limits.md +13 -13
  49. package/scaffold/.agents/skills/hitch-theory/SKILL.md +3 -2
  50. package/scaffold/.agents/skills/react-best-practices/SKILL.md +127 -0
  51. package/scaffold/.agents/skills/react-best-practices/rules/advanced-effect-event-deps.md +50 -0
  52. package/scaffold/.agents/skills/react-best-practices/rules/advanced-event-handler-refs.md +55 -0
  53. package/scaffold/.agents/skills/react-best-practices/rules/advanced-init-once.md +42 -0
  54. package/scaffold/.agents/skills/react-best-practices/rules/advanced-use-latest.md +39 -0
  55. package/scaffold/.agents/skills/react-best-practices/rules/async-cheap-condition-before-await.md +37 -0
  56. package/scaffold/.agents/skills/react-best-practices/rules/async-defer-await.md +82 -0
  57. package/scaffold/.agents/skills/react-best-practices/rules/async-dependencies.md +48 -0
  58. package/scaffold/.agents/skills/react-best-practices/rules/async-parallel.md +24 -0
  59. package/scaffold/.agents/skills/react-best-practices/rules/bundle-analyzable-paths.md +42 -0
  60. package/scaffold/.agents/skills/react-best-practices/rules/bundle-barrel-imports.md +39 -0
  61. package/scaffold/.agents/skills/react-best-practices/rules/bundle-conditional.md +35 -0
  62. package/scaffold/.agents/skills/react-best-practices/rules/bundle-defer-third-party.md +46 -0
  63. package/scaffold/.agents/skills/react-best-practices/rules/bundle-dynamic-imports.md +38 -0
  64. package/scaffold/.agents/skills/react-best-practices/rules/bundle-preload.md +40 -0
  65. package/scaffold/.agents/skills/react-best-practices/rules/client-event-listeners.md +78 -0
  66. package/scaffold/.agents/skills/react-best-practices/rules/client-localstorage-schema.md +74 -0
  67. package/scaffold/.agents/skills/react-best-practices/rules/client-passive-event-listeners.md +48 -0
  68. package/scaffold/.agents/skills/react-best-practices/rules/js-batch-dom-css.md +110 -0
  69. package/scaffold/.agents/skills/react-best-practices/rules/js-cache-function-results.md +58 -0
  70. package/scaffold/.agents/skills/react-best-practices/rules/js-cache-property-access.md +28 -0
  71. package/scaffold/.agents/skills/react-best-practices/rules/js-cache-storage.md +56 -0
  72. package/scaffold/.agents/skills/react-best-practices/rules/js-combine-iterations.md +32 -0
  73. package/scaffold/.agents/skills/react-best-practices/rules/js-early-exit.md +50 -0
  74. package/scaffold/.agents/skills/react-best-practices/rules/js-flatmap-filter.md +51 -0
  75. package/scaffold/.agents/skills/react-best-practices/rules/js-hoist-regexp.md +45 -0
  76. package/scaffold/.agents/skills/react-best-practices/rules/js-index-maps.md +37 -0
  77. package/scaffold/.agents/skills/react-best-practices/rules/js-length-check-first.md +50 -0
  78. package/scaffold/.agents/skills/react-best-practices/rules/js-min-max-loop.md +82 -0
  79. package/scaffold/.agents/skills/react-best-practices/rules/js-request-idle-callback.md +104 -0
  80. package/scaffold/.agents/skills/react-best-practices/rules/js-set-map-lookups.md +24 -0
  81. package/scaffold/.agents/skills/react-best-practices/rules/js-tosorted-immutable.md +57 -0
  82. package/scaffold/.agents/skills/react-best-practices/rules/rendering-activity.md +26 -0
  83. package/scaffold/.agents/skills/react-best-practices/rules/rendering-animate-svg-wrapper.md +38 -0
  84. package/scaffold/.agents/skills/react-best-practices/rules/rendering-conditional-render.md +32 -0
  85. package/scaffold/.agents/skills/react-best-practices/rules/rendering-content-visibility.md +38 -0
  86. package/scaffold/.agents/skills/react-best-practices/rules/rendering-hoist-jsx.md +36 -0
  87. package/scaffold/.agents/skills/react-best-practices/rules/rendering-resource-hints.md +81 -0
  88. package/scaffold/.agents/skills/react-best-practices/rules/rendering-script-defer-async.md +36 -0
  89. package/scaffold/.agents/skills/react-best-practices/rules/rendering-svg-precision.md +28 -0
  90. package/scaffold/.agents/skills/react-best-practices/rules/rendering-usetransition-loading.md +43 -0
  91. package/scaffold/.agents/skills/react-best-practices/rules/rerender-defer-reads.md +39 -0
  92. package/scaffold/.agents/skills/react-best-practices/rules/rerender-dependencies.md +45 -0
  93. package/scaffold/.agents/skills/react-best-practices/rules/rerender-derived-state-no-effect.md +40 -0
  94. package/scaffold/.agents/skills/react-best-practices/rules/rerender-derived-state.md +29 -0
  95. package/scaffold/.agents/skills/react-best-practices/rules/rerender-functional-setstate.md +77 -0
  96. package/scaffold/.agents/skills/react-best-practices/rules/rerender-lazy-state-init.md +56 -0
  97. package/scaffold/.agents/skills/react-best-practices/rules/rerender-memo-with-default-value.md +36 -0
  98. package/scaffold/.agents/skills/react-best-practices/rules/rerender-memo.md +44 -0
  99. package/scaffold/.agents/skills/react-best-practices/rules/rerender-move-effect-to-event.md +45 -0
  100. package/scaffold/.agents/skills/react-best-practices/rules/rerender-no-inline-components.md +75 -0
  101. package/scaffold/.agents/skills/react-best-practices/rules/rerender-simple-expression-in-memo.md +35 -0
  102. package/scaffold/.agents/skills/react-best-practices/rules/rerender-split-combined-hooks.md +64 -0
  103. package/scaffold/.agents/skills/react-best-practices/rules/rerender-transitions.md +40 -0
  104. package/scaffold/.agents/skills/react-best-practices/rules/rerender-use-deferred-value.md +59 -0
  105. package/scaffold/.agents/skills/react-best-practices/rules/rerender-use-ref-transient-values.md +73 -0
  106. package/scaffold/.agents/skills/tanstack-query/SKILL.md +136 -0
  107. package/scaffold/.agents/skills/tanstack-query/references/compositions/automatic-invalidation-after-mutations.md +124 -0
  108. package/scaffold/.agents/skills/tanstack-query/references/compositions/broadcast-realtime-and-multi-tab-synchronization.md +150 -0
  109. package/scaffold/.agents/skills/tanstack-query/references/compositions/compose-query-with-tanstack-router-and-start.md +248 -0
  110. package/scaffold/.agents/skills/tanstack-query/references/compositions/enforce-query-best-practices-with-eslint.md +167 -0
  111. package/scaffold/.agents/skills/tanstack-query/references/compositions/persist-offline-and-restore-caches.md +181 -0
  112. package/scaffold/.agents/skills/tanstack-query/references/compositions/query-data-and-forms.md +156 -0
  113. package/scaffold/.agents/skills/tanstack-query/references/core/build-query-abstractions.md +130 -0
  114. package/scaffold/.agents/skills/tanstack-query/references/core/cancel-queries-and-consume-abort-signals.md +176 -0
  115. package/scaffold/.agents/skills/tanstack-query/references/core/concurrent-optimistic-updates.md +135 -0
  116. package/scaffold/.agents/skills/tanstack-query/references/core/coordinate-query-execution.md +188 -0
  117. package/scaffold/.agents/skills/tanstack-query/references/core/design-query-keys-and-options.md +182 -0
  118. package/scaffold/.agents/skills/tanstack-query/references/core/fetch-and-observe-queries.md +193 -0
  119. package/scaffold/.agents/skills/tanstack-query/references/core/implement-optimistic-updates-and-cache-writes.md +168 -0
  120. package/scaffold/.agents/skills/tanstack-query/references/core/paginate-and-build-infinite-queries.md +188 -0
  121. package/scaffold/.agents/skills/tanstack-query/references/core/seed-placeholder-select-and-transform-data.md +188 -0
  122. package/scaffold/.agents/skills/tanstack-query/references/core/selectors-and-derived-state.md +145 -0
  123. package/scaffold/.agents/skills/tanstack-query/references/core/tune-defaults-freshness-retries-and-refetching.md +172 -0
  124. package/scaffold/.agents/skills/tanstack-query/references/core/understand-query-internals-and-observers.md +104 -0
  125. package/scaffold/.agents/skills/tanstack-query/references/core/write-mutations-and-invalidate-related-queries.md +183 -0
  126. package/scaffold/.agents/skills/tanstack-query/references/framework/debug-with-devtools.md +169 -0
  127. package/scaffold/.agents/skills/tanstack-query/references/framework/handle-status-and-errors.md +119 -0
  128. package/scaffold/.agents/skills/tanstack-query/references/framework/shape-data-and-render-efficiently.md +184 -0
  129. package/scaffold/.agents/skills/tanstack-query/references/framework/use-framework-adapter-reactivity.md +185 -0
  130. package/scaffold/.agents/skills/tanstack-query/references/framework/use-suspense-and-error-boundaries.md +208 -0
  131. package/scaffold/.agents/skills/tanstack-query/references/lifecycle/migrate-major-versions-and-codemods.md +169 -0
  132. package/scaffold/.agents/skills/tanstack-query/references/lifecycle/prefetch-and-remove-request-waterfalls.md +228 -0
  133. package/scaffold/.agents/skills/tanstack-query/references/lifecycle/setup-query-client-and-providers.md +161 -0
  134. package/scaffold/.agents/skills/tanstack-query/references/lifecycle/ssr-hydration-and-streaming.md +209 -0
  135. package/scaffold/.agents/skills/tanstack-query/references/lifecycle/test-query-code.md +160 -0
  136. package/scaffold/.agents/skills/tanstack-router/SKILL.md +134 -0
  137. package/scaffold/.agents/skills/tanstack-router/references/compositions/router-query.md +412 -0
  138. package/scaffold/.agents/skills/tanstack-router/references/react-router.md +495 -0
  139. package/scaffold/.agents/skills/tanstack-router/references/router-core/auth-and-guards.md +495 -0
  140. package/scaffold/.agents/skills/tanstack-router/references/router-core/code-splitting.md +318 -0
  141. package/scaffold/.agents/skills/tanstack-router/references/router-core/data-loading.md +490 -0
  142. package/scaffold/.agents/skills/tanstack-router/references/router-core/index.md +158 -0
  143. package/scaffold/.agents/skills/tanstack-router/references/router-core/navigation.md +433 -0
  144. package/scaffold/.agents/skills/tanstack-router/references/router-core/not-found-and-errors.md +436 -0
  145. package/scaffold/.agents/skills/tanstack-router/references/router-core/path-params.md +383 -0
  146. package/scaffold/.agents/skills/tanstack-router/references/router-core/search-params.md +343 -0
  147. package/scaffold/.agents/skills/tanstack-router/references/router-core/ssr.md +462 -0
  148. package/scaffold/.agents/skills/tanstack-router/references/router-core/type-safety.md +493 -0
  149. package/scaffold/.agents/skills/tanstack-router/references/router-plugin.md +250 -0
  150. package/scaffold/.agents/skills/tanstack-router/references/virtual-file-routes.md +215 -0
  151. package/scaffold/.agents/skills/web-design-guidelines/SKILL.md +184 -0
  152. package/scaffold/.github/workflows/hitch.yml +1 -1
  153. package/scaffold/AGENTS.md +2 -2
  154. package/scaffold/applet/src/client/components/ui/alert.tsx +1 -1
  155. package/scaffold/applet/src/client/components/ui/button.tsx +1 -1
  156. package/scaffold/applet/src/client/components/ui/checkbox.tsx +1 -1
  157. package/scaffold/applet/src/client/components/ui/dialog.tsx +2 -2
  158. package/scaffold/applet/src/client/components/ui/dropdown-menu.tsx +2 -2
  159. package/scaffold/applet/src/client/components/ui/input-group.tsx +2 -2
  160. package/scaffold/applet/src/client/components/ui/select.tsx +2 -2
  161. package/scaffold/applet/src/client/components/ui/sheet.tsx +2 -2
  162. package/scaffold/applet/src/client/components/ui/spinner.tsx +2 -1
  163. package/scaffold/applet/src/client/components/ui/tabs.tsx +1 -1
  164. package/scaffold/applet/src/client/lib/utils.ts +1 -6
  165. package/scaffold/applet/src/client/styles/globals.css +2 -0
  166. package/dist/build-CFCKKMn7.js +0 -2
  167. package/dist/generate-CQ07Hdpo.js +0 -2
@@ -0,0 +1,250 @@
1
+ ---
2
+ name: router-plugin
3
+ description: >-
4
+ TanStack Router bundler plugin for route generation and automatic
5
+ code splitting. Supports Vite, Webpack, Rspack, and esbuild.
6
+ Configures autoCodeSplitting, routesDirectory, target framework,
7
+ and code split groupings.
8
+ metadata:
9
+ type: core
10
+ library: tanstack-router
11
+ library_version: "1.168.23"
12
+ sources:
13
+ - TanStack/router:packages/router-plugin/src
14
+ - TanStack/router:docs/router/routing/file-based-routing.md
15
+ - TanStack/router:docs/router/guide/code-splitting.md
16
+ ---
17
+
18
+ # Router Plugin (`@tanstack/router-plugin`)
19
+
20
+ Bundler plugin that powers TanStack Router's file-based routing and automatic code splitting. Works with Vite, Webpack, Rspack, and esbuild via unplugin.
21
+
22
+ > **CRITICAL**: The router plugin MUST come before the framework plugin (React, Solid, Vue) in the Vite config. Wrong order causes route generation and code splitting to fail silently.
23
+
24
+ ## Install
25
+
26
+ ```bash
27
+ npm install -D @tanstack/router-plugin
28
+ ```
29
+
30
+ ## Bundler Setup
31
+
32
+ ### Vite (most common)
33
+
34
+ ```ts
35
+ // vite.config.ts
36
+ import { defineConfig } from "vite";
37
+ import react from "@vitejs/plugin-react";
38
+ import { tanstackRouter } from "@tanstack/router-plugin/vite";
39
+
40
+ export default defineConfig({
41
+ plugins: [
42
+ // MUST come before react()
43
+ tanstackRouter({
44
+ target: "react",
45
+ autoCodeSplitting: true,
46
+ }),
47
+ react(),
48
+ ],
49
+ });
50
+ ```
51
+
52
+ ### Webpack
53
+
54
+ ```ts
55
+ // webpack.config.js
56
+ const { tanstackRouter } = require("@tanstack/router-plugin/webpack");
57
+
58
+ module.exports = {
59
+ plugins: [
60
+ tanstackRouter({
61
+ target: "react",
62
+ autoCodeSplitting: true,
63
+ }),
64
+ ],
65
+ };
66
+ ```
67
+
68
+ ### Rspack
69
+
70
+ ```ts
71
+ // rspack.config.js
72
+ const { tanstackRouter } = require("@tanstack/router-plugin/rspack");
73
+
74
+ module.exports = {
75
+ plugins: [
76
+ tanstackRouter({
77
+ target: "react",
78
+ autoCodeSplitting: true,
79
+ }),
80
+ ],
81
+ };
82
+ ```
83
+
84
+ ### esbuild
85
+
86
+ ```ts
87
+ import { tanstackRouter } from "@tanstack/router-plugin/esbuild";
88
+ import esbuild from "esbuild";
89
+
90
+ esbuild.build({
91
+ plugins: [
92
+ tanstackRouter({
93
+ target: "react",
94
+ autoCodeSplitting: true,
95
+ }),
96
+ ],
97
+ });
98
+ ```
99
+
100
+ ## Configuration Options
101
+
102
+ ### Core Options
103
+
104
+ | Option | Type | Default | Description |
105
+ | ----------------------- | ----------------------------- | -------------------------- | ------------------------------------------ |
106
+ | `target` | `'react' \| 'solid' \| 'vue'` | `'react'` | Target framework |
107
+ | `routesDirectory` | `string` | `'./src/routes'` | Directory containing route files |
108
+ | `generatedRouteTree` | `string` | `'./src/routeTree.gen.ts'` | Path for generated route tree |
109
+ | `autoCodeSplitting` | `boolean` | `undefined` | Enable automatic code splitting |
110
+ | `enableRouteGeneration` | `boolean` | `true` | Set to `false` to disable route generation |
111
+
112
+ ### File Convention Options
113
+
114
+ | Option | Type | Default | Description |
115
+ | ------------------------ | ------------------------------------------------------- | ----------- | ------------------------------------ |
116
+ | `routeFilePrefix` | `string` | `undefined` | Prefix filter for route files |
117
+ | `routeFileIgnorePrefix` | `string` | `'-'` | Prefix to exclude files from routing |
118
+ | `routeFileIgnorePattern` | `string` | `undefined` | Pattern to exclude from routing |
119
+ | `indexToken` | `string \| RegExp \| { regex: string; flags?: string }` | `'index'` | Token identifying index routes |
120
+ | `routeToken` | `string \| RegExp \| { regex: string; flags?: string }` | `'route'` | Token identifying route config files |
121
+
122
+ ### Code Splitting Options
123
+
124
+ ```ts
125
+ tanstackRouter({
126
+ target: "react",
127
+ autoCodeSplitting: true,
128
+ codeSplittingOptions: {
129
+ // Default groupings for all routes
130
+ defaultBehavior: [["component"], ["errorComponent"], ["notFoundComponent"]],
131
+
132
+ // Per-route custom splitting
133
+ splitBehavior: ({ routeId }) => {
134
+ if (routeId === "/dashboard") {
135
+ // Keep loader and component together for dashboard
136
+ return [["loader", "component"], ["errorComponent"]];
137
+ }
138
+ // Return undefined to use defaultBehavior
139
+ },
140
+ },
141
+ });
142
+ ```
143
+
144
+ ### Output Options
145
+
146
+ | Option | Type | Default | Description |
147
+ | --------------------------- | ---------------------- | ---------- | -------------------------------- |
148
+ | `quoteStyle` | `'single' \| 'double'` | `'single'` | Quote style in generated code |
149
+ | `semicolons` | `boolean` | `false` | Use semicolons in generated code |
150
+ | `disableTypes` | `boolean` | `false` | Disable TypeScript types |
151
+ | `disableLogging` | `boolean` | `false` | Suppress plugin logs |
152
+ | `addExtensions` | `boolean \| string` | `false` | Add file extensions to imports |
153
+ | `enableRouteTreeFormatting` | `boolean` | `true` | Format generated route tree |
154
+
155
+ ### Virtual Route Config
156
+
157
+ ```ts
158
+ import { routes } from "./routes";
159
+
160
+ tanstackRouter({
161
+ target: "react",
162
+ virtualRouteConfig: routes, // or './routes.ts'
163
+ });
164
+ ```
165
+
166
+ ## How It Works
167
+
168
+ The composed plugin assembles up to 3 sub-plugins:
169
+
170
+ 1. **Route Generator** (always) — Watches route files and generates `routeTree.gen.ts`
171
+ 2. **Code Splitter** (when `autoCodeSplitting: true`) — Splits route files into lazy-loaded chunks using virtual modules
172
+ 3. **HMR** (dev mode, when code splitter is off) — Hot-reloads route changes without full refresh
173
+
174
+ ## Route Refactor Workflow
175
+
176
+ When moving, renaming, adding, or deleting file routes:
177
+
178
+ 1. Change the source files under `routesDirectory`. Keep the exported route identifier named `Route`.
179
+ 2. Let the bundler plugin regenerate the tree, or run `pnpm exec tsr generate` when the project uses the CLI.
180
+ 3. Inspect the generated diff for the expected route IDs, parents, paths, and imports. Never repair `routeTree.gen.ts` by hand.
181
+ 4. Update links, redirects, `from` narrowing, params, preload calls, and tests that reference the old route.
182
+ 5. Run route-generation tests, type tests, and a production build. A passing editor typecheck does not prove the plugin generated or split the new route correctly.
183
+
184
+ Commit `routeTree.gen.ts`; it is generated source used by the application at runtime.
185
+
186
+ ## Individual Plugin Exports
187
+
188
+ For advanced use, each sub-plugin is exported separately from the Vite entry:
189
+
190
+ ```ts
191
+ import {
192
+ tanstackRouter, // Composed (default)
193
+ tanstackRouterGenerator, // Generator only
194
+ tanStackRouterCodeSplitter, // Code splitter only
195
+ } from "@tanstack/router-plugin/vite";
196
+ ```
197
+
198
+ ## Common Mistakes
199
+
200
+ ### 1. CRITICAL: Wrong plugin order in Vite config
201
+
202
+ The router plugin must come before the framework plugin. Otherwise, route generation and code splitting fail silently.
203
+
204
+ ```ts
205
+ // WRONG — react() before tanstackRouter()
206
+ plugins: [react(), tanstackRouter({ target: "react" })];
207
+
208
+ // CORRECT — tanstackRouter() first
209
+ plugins: [tanstackRouter({ target: "react" }), react()];
210
+ ```
211
+
212
+ ### 2. HIGH: Missing target option for non-React frameworks
213
+
214
+ The `target` defaults to `'react'`. For Solid or Vue, you must set it explicitly.
215
+
216
+ ```ts
217
+ // WRONG for Solid — generates React imports
218
+ tanstackRouter({ autoCodeSplitting: true });
219
+
220
+ // CORRECT for Solid
221
+ tanstackRouter({ target: "solid", autoCodeSplitting: true });
222
+ ```
223
+
224
+ ### 3. MEDIUM: Confusing autoCodeSplitting with manual lazy routes
225
+
226
+ When `autoCodeSplitting` is enabled, the plugin handles splitting automatically. You do NOT need manual `createLazyRoute` or `lazyRouteComponent` calls — the plugin transforms your route files at build time.
227
+
228
+ ```tsx
229
+ // WRONG — manual lazy loading with autoCodeSplitting enabled
230
+ const LazyAbout = lazyRouteComponent(() => import("./about"));
231
+
232
+ // CORRECT — just write normal route files, plugin handles splitting
233
+ // src/routes/about.tsx
234
+ export const Route = createFileRoute("/about")({
235
+ component: AboutPage,
236
+ });
237
+
238
+ function AboutPage() {
239
+ return <h1>About</h1>;
240
+ }
241
+ ```
242
+
243
+ ### 4. HIGH: Editing the generated route tree
244
+
245
+ Changes to `routeTree.gen.ts` are overwritten and can leave source routes, generated types, and runtime routing out of sync. Fix route filenames or plugin configuration, regenerate, and verify the generated diff instead.
246
+
247
+ ## Cross-References
248
+
249
+ - [router-core/code-splitting](router-core/code-splitting.md) — manual code splitting concepts
250
+ - [virtual-file-routes](virtual-file-routes.md) — programmatic route trees
@@ -0,0 +1,215 @@
1
+ ---
2
+ name: virtual-file-routes
3
+ description: >-
4
+ Programmatic route tree building as an alternative to filesystem
5
+ conventions: rootRoute, index, route, layout, physical,
6
+ defineVirtualSubtreeConfig. Use with TanStack Router plugin's
7
+ virtualRouteConfig option.
8
+ metadata:
9
+ type: core
10
+ library: tanstack-router
11
+ library_version: "1.162.0"
12
+ sources:
13
+ - TanStack/router:packages/virtual-file-routes/src
14
+ - TanStack/router:docs/router/routing/virtual-file-routes.md
15
+ ---
16
+
17
+ # Virtual File Routes (`@tanstack/virtual-file-routes`)
18
+
19
+ Build route trees programmatically instead of relying on filesystem conventions. Useful when you want explicit control over route structure, need to mix virtual and physical routes, or want to define route subtrees within file-based routing directories.
20
+
21
+ Use this skill only when the project config contains `virtualRouteConfig`, a virtual route config file, or `__virtual.ts`. Ordinary file-route changes belong to Router Core and the Router Plugin.
22
+
23
+ > **CRITICAL**: Types are FULLY INFERRED. Never cast, never annotate inferred values.
24
+
25
+ ## Install
26
+
27
+ ```bash
28
+ npm install @tanstack/virtual-file-routes
29
+ ```
30
+
31
+ ## API Reference
32
+
33
+ ### `rootRoute(file, children?)`
34
+
35
+ Creates the root of a virtual route tree.
36
+
37
+ ```ts
38
+ import { rootRoute, index, route } from "@tanstack/virtual-file-routes";
39
+
40
+ const routes = rootRoute("root.tsx", [index("index.tsx"), route("/about", "about.tsx")]);
41
+ ```
42
+
43
+ ### `index(file)`
44
+
45
+ Creates an index route — the default rendered when the parent path matches exactly.
46
+
47
+ ```ts
48
+ import { index } from "@tanstack/virtual-file-routes";
49
+
50
+ index("home.tsx");
51
+ ```
52
+
53
+ ### `route(path, ...)`
54
+
55
+ Creates a route node. Three call signatures:
56
+
57
+ ```ts
58
+ import { route, index } from "@tanstack/virtual-file-routes";
59
+
60
+ // Leaf route: path + file
61
+ route("/about", "about.tsx");
62
+
63
+ // Branch route: path + file + children
64
+ route("/dashboard", "dashboard.tsx", [
65
+ index("dashboard-index.tsx"),
66
+ route("/settings", "settings.tsx"),
67
+ ]);
68
+
69
+ // Path prefix only (no file): groups children under a URL segment
70
+ route("/api", [route("/users", "users.tsx"), route("/posts", "posts.tsx")]);
71
+ ```
72
+
73
+ ### `layout(file, children)` or `layout(id, file, children)`
74
+
75
+ Creates a pathless layout route — wraps children without adding a URL segment.
76
+
77
+ ```ts
78
+ import { layout, route, index } from "@tanstack/virtual-file-routes";
79
+
80
+ // ID derived from filename
81
+ layout("authLayout.tsx", [
82
+ route("/dashboard", "dashboard.tsx"),
83
+ route("/settings", "settings.tsx"),
84
+ ]);
85
+
86
+ // Explicit ID
87
+ layout("admin-layout", "adminLayout.tsx", [route("/admin", "admin.tsx")]);
88
+ ```
89
+
90
+ ### `physical(pathPrefix, directory)` or `physical(directory)`
91
+
92
+ Mounts a directory of file-based routes at a URL prefix. Uses TanStack Router's standard file-based routing conventions within that directory.
93
+
94
+ ```ts
95
+ import { physical } from "@tanstack/virtual-file-routes";
96
+
97
+ // Mount posts/ directory under /posts
98
+ physical("/posts", "posts");
99
+
100
+ // Merge features/ directory at the current level
101
+ physical("features");
102
+ ```
103
+
104
+ ### `defineVirtualSubtreeConfig(config)`
105
+
106
+ Type helper for `__virtual.ts` files inside file-based routing directories. Identity function that provides type inference.
107
+
108
+ ```ts
109
+ // src/routes/admin/__virtual.ts
110
+ import { defineVirtualSubtreeConfig, index, route } from "@tanstack/virtual-file-routes";
111
+
112
+ export default defineVirtualSubtreeConfig([index("home.tsx"), route("$id", "details.tsx")]);
113
+ ```
114
+
115
+ ## Integration with Router Plugin
116
+
117
+ Pass the virtual route config to the TanStack Router plugin:
118
+
119
+ ```ts
120
+ // vite.config.ts
121
+ import { defineConfig } from "vite";
122
+ import { tanstackRouter } from "@tanstack/router-plugin/vite";
123
+ import { routes } from "./routes";
124
+
125
+ export default defineConfig({
126
+ plugins: [
127
+ tanstackRouter({
128
+ target: "react", // or 'solid', 'vue'
129
+ virtualRouteConfig: routes,
130
+ }),
131
+ // Add your framework's Vite plugin here
132
+ ],
133
+ });
134
+ ```
135
+
136
+ Or reference a file path:
137
+
138
+ ```ts
139
+ tanstackRouter({
140
+ target: "react",
141
+ virtualRouteConfig: "./routes.ts",
142
+ });
143
+ ```
144
+
145
+ ## Full Example
146
+
147
+ ```ts
148
+ // routes.ts
149
+ import { rootRoute, route, index, layout, physical } from "@tanstack/virtual-file-routes";
150
+
151
+ export const routes = rootRoute("root.tsx", [
152
+ index("index.tsx"),
153
+
154
+ layout("authLayout.tsx", [
155
+ route("/dashboard", "app/dashboard.tsx", [
156
+ index("app/dashboard-index.tsx"),
157
+ route("/invoices", "app/dashboard-invoices.tsx", [
158
+ index("app/invoices-index.tsx"),
159
+ route("$id", "app/invoice-detail.tsx"),
160
+ ]),
161
+ ]),
162
+ ]),
163
+
164
+ // Mount file-based routing from posts/ directory
165
+ physical("/posts", "posts"),
166
+ ]);
167
+ ```
168
+
169
+ ## Common Mistakes
170
+
171
+ ### 1. HIGH: Forgetting that file paths are relative to routesDirectory
172
+
173
+ File paths in `rootRoute`, `index`, `route`, and `layout` are relative to the `routesDirectory` configured in the router plugin (default: `./src/routes`). Do not use absolute paths or paths relative to the project root.
174
+
175
+ ```ts
176
+ // WRONG — absolute path
177
+ route("/about", "/src/routes/about.tsx");
178
+
179
+ // CORRECT — relative to routesDirectory
180
+ route("/about", "about.tsx");
181
+ ```
182
+
183
+ ### 2. MEDIUM: Using physical() without matching directory structure
184
+
185
+ The directory passed to `physical()` must exist inside `routesDirectory` and follow TanStack Router's file-based routing conventions.
186
+
187
+ ```ts
188
+ // WRONG — directory doesn't exist or wrong location
189
+ physical("/blog", "src/blog");
190
+
191
+ // CORRECT — relative to routesDirectory
192
+ physical("/blog", "blog");
193
+ // Expects: src/routes/blog/ (with route files inside)
194
+ ```
195
+
196
+ ### 3. MEDIUM: Confusing layout() with route()
197
+
198
+ `layout()` creates a pathless wrapper — it does NOT add a URL segment. Use `route()` for URL segments.
199
+
200
+ ```ts
201
+ // This does NOT create a /dashboard URL
202
+ layout("dashboardLayout.tsx", [route("/dashboard", "dashboard.tsx")]);
203
+
204
+ // The URL is /dashboard, and dashboardLayout.tsx wraps it
205
+ ```
206
+
207
+ ## Refactor Audit
208
+
209
+ After changing a virtual tree:
210
+
211
+ 1. Confirm there is exactly one `rootRoute` and that every referenced file exists relative to `routesDirectory`.
212
+ 2. Check each `route`, `layout`, and `physical` node for duplicate effective paths or IDs.
213
+ 3. Confirm each `physical()` directory is mounted once at the intended path prefix and does not overlap a virtual child.
214
+ 4. Regenerate `routeTree.gen.ts` and inspect parentage, full paths, and imports. Do not edit generated output.
215
+ 5. Update links, redirects, params, and `from` narrowing, then run generator tests, type tests, and a production build.
@@ -0,0 +1,184 @@
1
+ ---
2
+ name: web-design-guidelines
3
+ description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
4
+ metadata:
5
+ author: vercel
6
+ version: "1.0.0"
7
+ argument-hint: <file-or-pattern>
8
+ ---
9
+
10
+ # Web Interface Guidelines
11
+
12
+ Review these files for compliance: $ARGUMENTS
13
+
14
+ Read files, check against rules below. Output concise but comprehensive—sacrifice grammar for brevity. High signal-to-noise.
15
+
16
+ ## Rules
17
+
18
+ ### Accessibility
19
+
20
+ - Icon-only buttons need `aria-label`
21
+ - Form controls need `<label>` or `aria-label`
22
+ - Interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp`)
23
+ - `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
24
+ - Images need `alt` (or `alt=""` if decorative)
25
+ - Decorative icons need `aria-hidden="true"`
26
+ - Async updates (toasts, validation) need `aria-live="polite"`
27
+ - Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
28
+ - Headings hierarchical `<h1>`–`<h6>`; include skip link for main content
29
+ - `scroll-margin-top` on heading anchors
30
+
31
+ ### Focus States
32
+
33
+ - Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
34
+ - Never `outline-none` / `outline: none` without focus replacement
35
+ - Use `:focus-visible` over `:focus` (avoid focus ring on click)
36
+ - Group focus with `:focus-within` for compound controls
37
+
38
+ ### Forms
39
+
40
+ - Inputs need `autocomplete` and meaningful `name`
41
+ - Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
42
+ - Never block paste (`onPaste` + `preventDefault`)
43
+ - Labels clickable (`htmlFor` or wrapping control)
44
+ - Disable spellcheck on emails, codes, usernames (`spellCheck={false}`)
45
+ - Checkboxes/radios: label + control share single hit target (no dead zones)
46
+ - Submit button stays enabled until request starts; spinner during request
47
+ - Errors inline next to fields; focus first error on submit
48
+ - Placeholders end with `…` and show example pattern
49
+ - `autocomplete="off"` on non-auth fields to avoid password manager triggers
50
+ - Warn before navigation with unsaved changes (`beforeunload` or router guard)
51
+
52
+ ### Animation
53
+
54
+ - Honor `prefers-reduced-motion` (provide reduced variant or disable)
55
+ - Animate `transform`/`opacity` only (compositor-friendly)
56
+ - Never `transition: all`—list properties explicitly
57
+ - Set correct `transform-origin`
58
+ - SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
59
+ - Animations interruptible—respond to user input mid-animation
60
+
61
+ ### Typography
62
+
63
+ - `…` not `...`
64
+ - Curly quotes `"` `"` not straight `"`
65
+ - Non-breaking spaces: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
66
+ - Loading states end with `…`: `"Loading…"`, `"Saving…"`
67
+ - `font-variant-numeric: tabular-nums` for number columns/comparisons
68
+ - Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
69
+
70
+ ### Content Handling
71
+
72
+ - Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
73
+ - Flex children need `min-w-0` to allow text truncation
74
+ - Handle empty states—don't render broken UI for empty strings/arrays
75
+ - User-generated content: anticipate short, average, and very long inputs
76
+
77
+ ### Images
78
+
79
+ - `<img>` needs explicit `width` and `height` (prevents CLS)
80
+ - Below-fold images: `loading="lazy"`
81
+ - Above-fold critical images: `priority` or `fetchpriority="high"`
82
+
83
+ ### Performance
84
+
85
+ - Large lists (>50 items): virtualize (`virtua`, `content-visibility: auto`)
86
+ - No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
87
+ - Batch DOM reads/writes; avoid interleaving
88
+ - Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
89
+ - Add `<link rel="preconnect">` for CDN/asset domains
90
+ - Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
91
+
92
+ ### Navigation & State
93
+
94
+ - URL reflects state—filters, tabs, pagination, expanded panels in query params
95
+ - Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
96
+ - Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar)
97
+ - Destructive actions need confirmation modal or undo window—never immediate
98
+
99
+ ### Touch & Interaction
100
+
101
+ - `touch-action: manipulation` (prevents double-tap zoom delay)
102
+ - `-webkit-tap-highlight-color` set intentionally
103
+ - `overscroll-behavior: contain` in modals/drawers/sheets
104
+ - During drag: disable text selection, `inert` on dragged elements
105
+ - `autoFocus` sparingly—desktop only, single primary input; avoid on mobile
106
+
107
+ ### Safe Areas & Layout
108
+
109
+ - Full-bleed layouts need `env(safe-area-inset-*)` for notches
110
+ - Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
111
+ - Flex/grid over JS measurement for layout
112
+
113
+ ### Dark Mode & Theming
114
+
115
+ - `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
116
+ - `<meta name="theme-color">` matches page background
117
+ - Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
118
+
119
+ ### Locale & i18n
120
+
121
+ - Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
122
+ - Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
123
+ - Detect language via `Accept-Language` / `navigator.languages`, not IP
124
+ - Brand names, code tokens, identifiers: wrap with `translate="no"` to prevent garbled auto-translation
125
+
126
+ ### Hydration Safety
127
+
128
+ - Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
129
+ - Date/time rendering: guard against hydration mismatch (server vs client)
130
+ - `suppressHydrationWarning` only where truly needed
131
+
132
+ ### Hover & Interactive States
133
+
134
+ - Buttons/links need `hover:` state (visual feedback)
135
+ - Interactive states increase contrast: hover/active/focus more prominent than rest
136
+
137
+ ### Content & Copy
138
+
139
+ - Active voice: "Install the CLI" not "The CLI will be installed"
140
+ - Title Case for headings/buttons (Chicago style)
141
+ - Numerals for counts: "8 deployments" not "eight"
142
+ - Specific button labels: "Save API Key" not "Continue"
143
+ - Error messages include fix/next step, not just problem
144
+ - Second person; avoid first person
145
+ - `&` over "and" where space-constrained
146
+
147
+ ### Anti-patterns (flag these)
148
+
149
+ - `user-scalable=no` or `maximum-scale=1` disabling zoom
150
+ - `onPaste` with `preventDefault`
151
+ - `transition: all`
152
+ - `outline-none` without focus-visible replacement
153
+ - Inline `onClick` navigation without `<a>`
154
+ - `<div>` or `<span>` with click handlers (should be `<button>`)
155
+ - Images without dimensions
156
+ - Large arrays `.map()` without virtualization
157
+ - Form inputs without labels
158
+ - Icon buttons without `aria-label`
159
+ - Hardcoded date/number formats (use `Intl.*`)
160
+ - `autoFocus` without clear justification
161
+
162
+ ## Output Format
163
+
164
+ Group by file. Use `file:line` format (VS Code clickable). Terse findings.
165
+
166
+ ```text
167
+ ## src/Button.tsx
168
+
169
+ src/Button.tsx:42 - icon button missing aria-label
170
+ src/Button.tsx:18 - input lacks label
171
+ src/Button.tsx:55 - animation missing prefers-reduced-motion
172
+ src/Button.tsx:67 - transition: all → list properties
173
+
174
+ ## src/Modal.tsx
175
+
176
+ src/Modal.tsx:12 - missing overscroll-behavior: contain
177
+ src/Modal.tsx:34 - "..." → "…"
178
+
179
+ ## src/Card.tsx
180
+
181
+ ✓ pass
182
+ ```
183
+
184
+ State issue + location. Skip explanation unless fix non-obvious. No preamble.
@@ -12,4 +12,4 @@ jobs:
12
12
  contents: read
13
13
  id-token: write
14
14
  # Hitch verifies the called workflow's commit SHA from the OIDC token.
15
- uses: hitch-42/actions/.github/workflows/deploy.yml@1a76e4936f94730e20710b455fa0a06564929f39
15
+ uses: hitch-42/actions/.github/workflows/deploy.yml@cc7ab4f6eba51b31f73b0deaef4f6b86d43dc0dd
@@ -4,8 +4,8 @@ Before any command or file edit, read and follow `.agents/skills/hitch-applets/S
4
4
 
5
5
  Use `pnpm` for package commands.
6
6
 
7
- Edit only `hitch.config.ts`, each `applet.manifest.ts`, and files in an applet `src` directory.
8
- The applet CLI replaces all other workspace files.
7
+ The applet CLI refreshes its generated support files.
8
+ The CLI adds missing MCP servers without changing existing entries.
9
9
 
10
10
  ## What makes a good applet
11
11
 
@@ -1,5 +1,5 @@
1
- import * as React from "react";
2
1
  import { cva, type VariantProps } from "class-variance-authority";
2
+ import * as React from "react";
3
3
 
4
4
  import { cn } from "@/client/lib/utils";
5
5
 
@@ -1,7 +1,7 @@
1
1
  "use client";
2
2
 
3
- import type * as React from "react";
4
3
  import { cva, type VariantProps } from "class-variance-authority";
4
+ import type * as React from "react";
5
5
  import {
6
6
  Button as ButtonPrimitive,
7
7
  Link as LinkPrimitive,