@cyclone-ui/nextjs 0.0.15 → 0.0.16

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.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,14 @@
2
2
 
3
3
  # Changelog for Cyclone UI - Nextjs
4
4
 
5
+ ## [0.0.15](https://github.com/storm-software/cyclone-ui/releases/tag/nextjs%400.0.15) (11/03/2026)
6
+
7
+ ### Updated Dependencies
8
+
9
+ - Updated **state** to **v0.0.45**
10
+ - Updated **theme-builder** to **v0.0.33**
11
+ - Updated **tokens** to **v0.3.32**
12
+
5
13
  ## [0.0.14](https://github.com/storm-software/cyclone-ui/releases/tag/nextjs%400.0.14) (11/03/2026)
6
14
 
7
15
  ### Bug Fixes
package/README.md CHANGED
@@ -38,19 +38,23 @@ Wrap the Next.js config:
38
38
 
39
39
  ```ts
40
40
  // next.config.ts
41
- import { withCycloneUI } from "@cyclone-ui/nextjs";
41
+ import { withCycloneUI } from "@cyclone-ui/nextjs"
42
42
 
43
43
  export default withCycloneUI({
44
44
  reactStrictMode: true
45
- });
45
+ })
46
46
  ```
47
47
 
48
+ The wrapper also accepts a promised config or a sync/async Next.js config
49
+ function. Phase functions remain lazy and receive the original phase and context;
50
+ existing `cacheComponents` and `partialPrefetching` values are preserved.
51
+
48
52
  Render the provider in the root layout. The provider sets a class on `<html>`
49
53
  before React hydrates, so add `suppressHydrationWarning` there:
50
54
 
51
55
  ```tsx
52
56
  // app/layout.tsx
53
- import { CycloneUIProvider } from "@cyclone-ui/nextjs/provider";
57
+ import { CycloneUIProvider } from "@cyclone-ui/nextjs/provider"
54
58
 
55
59
  export default function RootLayout({
56
60
  children
@@ -63,19 +67,43 @@ export default function RootLayout({
63
67
  <CycloneUIProvider>{children}</CycloneUIProvider>
64
68
  </body>
65
69
  </html>
66
- );
70
+ )
71
+ }
72
+ ```
73
+
74
+ The layout remains a Server Component. The client provider accepts server-rendered
75
+ children without moving those child modules into the client bundle. Props that
76
+ cross this boundary must be serializable by React. The default config is already
77
+ imported inside the provider; if passing a custom Tamagui `config` or an ordinary
78
+ callback such as `onChangeTheme`, define them inside an application-owned client
79
+ wrapper:
80
+
81
+ ```tsx
82
+ // app/providers.tsx
83
+ "use client"
84
+
85
+ import { CycloneUIProvider } from "@cyclone-ui/nextjs/provider"
86
+ import type { PropsWithChildren } from "react"
87
+ import { config } from "@/tamagui.config" // Use your config's actual export.
88
+
89
+ export function AppProviders({ children }: PropsWithChildren) {
90
+ return <CycloneUIProvider config={config}>{children}</CycloneUIProvider>
67
91
  }
68
92
  ```
69
93
 
94
+ Render `<AppProviders>{children}</AppProviders>` from the server layout. The
95
+ build-time `tokens` option below also replaces the provider's config import, so
96
+ it needs no `config` prop.
97
+
70
98
  Read or change the theme with `useThemeSetting`:
71
99
 
72
100
  ```tsx
73
- "use client";
101
+ "use client"
74
102
 
75
- import { useThemeSetting } from "@cyclone-ui/nextjs/provider";
103
+ import { useThemeSetting } from "@cyclone-ui/nextjs/provider"
76
104
 
77
105
  export function ThemeToggle() {
78
- const theme = useThemeSetting();
106
+ const theme = useThemeSetting()
79
107
 
80
108
  return <button onClick={theme.toggle}>Change theme</button>
81
109
  }
@@ -91,21 +119,24 @@ System preference changes apply when the selected setting is `system`.
91
119
 
92
120
  ### Cache Components and static shells
93
121
 
94
- Enable the caching options explicitly in the consuming App Router app:
122
+ Cache Components in Next.js 16 includes Partial Prerendering (PPR): a prerendered
123
+ shell with dynamic content streamed through Suspense. Partial Prefetching is a
124
+ separate navigation feature introduced in Next.js 16.3 and requires Cache
125
+ Components. Check your installed Next.js version before adding flags. For
126
+ Next.js 16.3+ when adopting both features:
95
127
 
96
128
  ```ts
97
- import { withCycloneUI } from "@cyclone-ui/nextjs";
129
+ import { withCycloneUI } from "@cyclone-ui/nextjs"
98
130
 
99
131
  export default withCycloneUI({
100
132
  cacheComponents: true,
101
133
  partialPrefetching: true
102
- });
134
+ })
103
135
  ```
104
136
 
105
- `withCycloneUI` preserves these options; it does not enable them globally.
106
- `partialPrefetching` requires `cacheComponents` and a Next.js version that
107
- supports the option. It changes Link prefetch behavior to fetch the static App
108
- Shell; it does not make request-dependent content static.
137
+ `withCycloneUI` preserves these options; it does not enable them globally or
138
+ choose a caching policy. On Next.js 16.0–16.2, omit `partialPrefetching`. Do not
139
+ combine `cacheComponents` with the older `experimental.ppr` flag.
109
140
 
110
141
  Keep the root layout synchronous and render `CycloneUIProvider` directly around
111
142
  its children, as above. The provider does not read `cookies()` or `headers()`
@@ -117,22 +148,38 @@ Do not read a theme cookie in the root layout just to populate `mode`. `mode` is
117
148
  an SSR/hydration fallback, not the user's persisted preference. `modeCookie` is
118
149
  an optional client-written mirror of the resolved light/dark mode; it does not
119
150
  require a server cookie read or preserve the distinction between system and an
120
- explicit choice. If a server component needs request cookies, put that component
121
- under a local `<Suspense>` boundary. Do not put cookie reads inside `"use cache"`
122
- or move the whole provider behind that boundary. Cached Server Components can
123
- be passed as children through the client provider.
151
+ explicit choice. Put request reads such as `cookies()`, `headers()`, and
152
+ `searchParams` inside the component that needs them, under a local `<Suspense>`
153
+ boundary with a useful fallback. Do not put those reads inside `"use cache"` or
154
+ move the whole provider behind that boundary. Server Components, including
155
+ cached ones, can be passed as children through the client provider.
156
+
157
+ Static JSX needs no `"use cache"`. Cache reusable application data or server UI
158
+ according to its freshness and invalidation policy; keep uncached live work
159
+ behind local Suspense. Do not add the directive to client providers or client
160
+ primitives as a general optimization.
124
161
 
125
162
  Use semantic theme tokens and relative sub-themes such as `base` in the shell.
126
163
  Avoid choosing server markup or literal colors from a browser theme preference.
127
164
  Theme-dependent text from `useThemeSetting().current`, `resolvedTheme`,
128
- `useRootTheme`, or `useThemeMode` must wait until that component mounts. These values can differ
129
- between the server and the first browser render. The constant-label toggle
165
+ `useRootTheme`, or `useThemeMode` must wait until that component mounts. These
166
+ values can differ between the server and the first browser render. The constant-label toggle
130
167
  above needs no mount guard. If showing a current-mode label, guard only that
131
168
  label/control, keeping the rest of the shell rendered. `suppressHydrationWarning`
132
169
  on `<html>` does not suppress mismatches in descendants.
133
170
 
134
- See [Next.js caching](https://nextjs.org/docs/app/getting-started/caching) and
135
- [partialPrefetching](https://nextjs.org/docs/app/api-reference/config/next-config-js/partialPrefetching).
171
+ With Partial Prefetching enabled, default links prefetch a reusable route App
172
+ Shell rather than all of a destination's content. Use `prefetch={true}` on
173
+ selected application links to also resolve cached URL-specific content depending
174
+ on `params`, `searchParams`, or the full URL. It no longer includes uncached
175
+ dynamic content from the legacy full prefetch; that content streams after
176
+ navigation. Audit existing `prefetch={true}` links before enabling the flag, and
177
+ verify concrete URL navigations in production. Avoid imposing full prefetching
178
+ on every shared link primitive.
179
+
180
+ See [Next.js caching](https://nextjs.org/docs/app/getting-started/caching),
181
+ [adopting Partial Prefetching](https://nextjs.org/docs/app/guides/adopting-partial-prefetching),
182
+ and [optimizing prefetching](https://nextjs.org/docs/app/guides/optimizing-prefetching).
136
183
 
137
184
  ### Custom design tokens
138
185
 
@@ -142,7 +189,7 @@ globs relative to the working directory:
142
189
 
143
190
  ```ts
144
191
  // next.config.ts
145
- import { withCycloneUI } from "@cyclone-ui/nextjs";
192
+ import { withCycloneUI } from "@cyclone-ui/nextjs"
146
193
 
147
194
  export default withCycloneUI(
148
195
  { reactStrictMode: true },
@@ -153,7 +200,7 @@ export default withCycloneUI(
153
200
  "tokens/dark.tokens.json"
154
201
  ]
155
202
  }
156
- );
203
+ )
157
204
  ```
158
205
 
159
206
  Files with a theme name (`light.tokens.json`, `dark.tokens.json`, …) become
@@ -161,8 +208,10 @@ the `light` and `dark` themes. The tokens go through the same preprocessor and
161
208
  generator as `@cyclone-ui/tokens`, and a `razorwind.config.ts` in the project
162
209
  still applies (for example its fonts).
163
210
 
164
- With `tokens`, `withCycloneUI` returns a promise, which Next.js accepts as the
165
- config export. The config is written to `.cyclone-ui/tamagui.config.ts`
211
+ With `tokens` and an object config, `withCycloneUI` returns a promise, which
212
+ Next.js accepts as the config export. For a phase function, token generation runs
213
+ when Next.js resolves that function. Compose object-only third-party wrappers
214
+ before the token build. The config is written to `.cyclone-ui/tamagui.config.ts`
166
215
  (add `.cyclone-ui` to `.gitignore`) and replaces `@cyclone-ui/tokens/tamagui`
167
216
  everywhere, so `CycloneUIProvider` and the Webpack compiler use it. With
168
217
  pnpm, Webpack builds also need `@tamagui/web` and `motion` installed in the
@@ -177,7 +226,7 @@ project root.
177
226
 
178
227
  | Prop | Default | Description |
179
228
  | ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------ |
180
- | `config` | The config from `@cyclone-ui/tokens/tamagui` | The Tamagui config |
229
+ | `config` | The config from `@cyclone-ui/tokens/tamagui` | The Tamagui config; import custom configs inside a client wrapper |
181
230
  | `disableInjectCSS` | `false` | Skip runtime theme CSS when the app imports CSS generated by the Tamagui compiler |
182
231
  | `skipNextHead` | `true` | Render the theme script inline. Set `false` in the Pages Router to use `next/script` |
183
232
  | `mode` | `"light"` | The fallback mode shared by the server and initial client render |
@@ -197,7 +246,7 @@ export default withCycloneUI(nextConfig, {
197
246
  ? "./public/tamagui.generated.css"
198
247
  : null,
199
248
  disableExtraction: process.env.NODE_ENV === "development"
200
- });
249
+ })
201
250
  ```
202
251
 
203
252
  The defaults are `config: "@cyclone-ui/tokens/tamagui"`,
@@ -220,26 +269,26 @@ it with the Tamagui CLI (`@tamagui/cli`) before `next build`:
220
269
  ## Development
221
270
 
222
271
  ```bash
223
- pnpm nx run nextjs:build
224
- ```
225
-
226
- The production integration fixture exercises the source provider with Cache
227
- Components and Partial Prefetching. From the workspace root (Node 22.18+ for
228
- TypeScript imports in the fixture config), build and start it:
229
-
230
- ```bash
231
- devenv shell -- env NODE_ENV=production node packages/nextjs/node_modules/next/dist/bin/next build packages/nextjs/test/fixture
232
- devenv shell -- env NODE_ENV=production node packages/nextjs/node_modules/next/dist/bin/next start packages/nextjs/test/fixture -p 3197
272
+ devenv shell -- pnpm nx run nextjs:build
233
273
  ```
234
274
 
235
- In another terminal, run the browser checks with Playwright Chromium installed:
275
+ The production integration rig exercises the source provider with Cache
276
+ Components and Partial Prefetching. From the workspace root, run:
236
277
 
237
278
  ```bash
238
- devenv shell -- node packages/nextjs/test/theme.browser.mjs
279
+ devenv shell -- pnpm --filter @cyclone-ui/nextjs exec playwright test
239
280
  ```
240
281
 
241
- `CHROMIUM_PATH` selects an existing Chromium executable; `TEST_URL` overrides
242
- `http://localhost:3197`. The checks cover shell CSS before hydration, persisted
243
- preferences, forced themes, system changes, cookies, streamed content, and client
244
- navigation. They use a mount-safe diagnostic label because a shared shell cannot
245
- know the browser's stored preference.
282
+ The Playwright config builds and starts the fixture automatically, setting
283
+ `EXPOSE_TESTING_API=1` for both build and start so the raw Next.js config can
284
+ enable the test API. Use Node 22.18+ for the fixture config's TypeScript imports.
285
+ `CHROMIUM_PATH` selects an existing Chromium executable; otherwise Playwright
286
+ uses its installed browser. See [instant-nav.rig.md](./instant-nav.rig.md) for
287
+ the rig and its assertions.
288
+
289
+ The checks hold request content back to inspect the immediate shell on initial
290
+ load and client navigation, then verify the streamed content arrives. They also
291
+ run `test/theme.browser.mjs` against the production server to cover shell CSS
292
+ before hydration, persisted preferences, forced themes, system changes, cookies,
293
+ and delayed hydration. The theme checks use a mount-safe diagnostic label because
294
+ a shared shell cannot know the browser's stored preference.
package/dist/index.cjs CHANGED
@@ -1 +1 @@
1
- Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("node:module"),t=require("node:path");const n=(n,r,i)=>({...n,env:{TAMAGUI_TARGET:`web`,...n.env},turbopack:{...n.turbopack,resolveAlias:{"react-native":`react-native-web`,"react-native-svg":`@tamagui/react-native-svg`,...i&&{"@cyclone-ui/tokens/tamagui":`./${(0,t.relative)(process.cwd(),i)}`},...n.turbopack?.resolveAlias}},webpack:(a,o)=>{let{withTamagui:s}=(0,e.createRequire)((0,t.join)(o.dir,`package.json`))(`@tamagui/next-plugin`),c=s({config:i??`@cyclone-ui/tokens/tamagui`,components:[`@tamagui/core`],appDir:!0,...r})(n).webpack(a,o);return i&&(c.resolve.alias[`@cyclone-ui/tokens/tamagui$`]=i),c}});function r(e={},{tokens:t,...r}={}){return t?import(`@cyclone-ui/theme-builder`).then(async({buildTamaguiConfig:e})=>e({tokens:t})).then(t=>n(e,r,t)):n(e,r)}exports.withCycloneUI=r;
1
+ Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("node:module"),t=require("node:path");const n=(n,r,i)=>({...n,env:{TAMAGUI_TARGET:`web`,...n.env},turbopack:{...n.turbopack,resolveAlias:{"react-native":`react-native-web`,"react-native-svg":`@tamagui/react-native-svg`,...i&&{"@cyclone-ui/tokens/tamagui":`./${(0,t.relative)(process.cwd(),i)}`},...n.turbopack?.resolveAlias}},webpack:(a,o)=>{let{withTamagui:s}=(0,e.createRequire)((0,t.join)(o.dir,`package.json`))(`@tamagui/next-plugin`),c=s({config:i??`@cyclone-ui/tokens/tamagui`,components:[`@tamagui/core`],appDir:!0,...r})(n).webpack(a,o);return i&&(c.resolve.alias[`@cyclone-ui/tokens/tamagui$`]=i),c}}),r=(e,{tokens:t,...i})=>e instanceof Promise?e.then(e=>r(e,{tokens:t,...i})):t?import(`@cyclone-ui/theme-builder`).then(async({buildTamaguiConfig:e})=>e({tokens:t})).then(t=>n(e,i,t)):n(e,i);function i(e={},t={}){return typeof e==`function`?(n,i)=>r(e(n,i),t):r(e,t)}exports.withCycloneUI=i;
package/dist/index.d.cts CHANGED
@@ -22,6 +22,9 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
22
22
  */
23
23
  tokens?: BuildTamaguiConfigOptions["tokens"];
24
24
  };
25
+ type NextConfigFunction<Result extends NextConfig | Promise<NextConfig> = NextConfig | Promise<NextConfig>> = (phase: string, context: {
26
+ defaultConfig: NextConfig;
27
+ }) => Result;
25
28
  /**
26
29
  * Wrap a Next.js config with the setup Tamagui and Cyclone UI components need.
27
30
  *
@@ -34,6 +37,8 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
34
37
  *
35
38
  * With `tokens`, the Tamagui config is built from them first, so this returns
36
39
  * a promise, which Next.js accepts as the config export.
40
+ * Phase functions receive Next.js's original phase and default config and
41
+ * remain lazy; async functions and promised configs are resolved before setup.
37
42
  *
38
43
  * Turbopack builds don't run the Tamagui compiler. To optimize them, use the
39
44
  * Tamagui CLI: `tamagui build --target web ./src -- next build`.
@@ -54,7 +59,7 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
54
59
  * export default withCycloneUI({}, { tokens: "tokens/**\/*.json" });
55
60
  * ```
56
61
  *
57
- * @param nextConfig - The Next.js config to extend.
62
+ * @param nextConfig - The Next.js config, promise, or phase function to extend.
58
63
  * @param options - The design `tokens`, plus options forwarded to
59
64
  * `@tamagui/next-plugin` (Webpack only).
60
65
  * @returns The extended Next.js config.
@@ -63,5 +68,10 @@ declare function withCycloneUI(nextConfig?: NextConfig, options?: WithCycloneUIO
63
68
  tokens?: undefined;
64
69
  }): NextConfig;
65
70
  declare function withCycloneUI(nextConfig: NextConfig | undefined, options: WithCycloneUIOptions): NextConfig | Promise<NextConfig>;
71
+ declare function withCycloneUI(nextConfig: Promise<NextConfig>, options?: WithCycloneUIOptions): Promise<NextConfig>;
72
+ declare function withCycloneUI<Result extends NextConfig | Promise<NextConfig>>(nextConfig: NextConfigFunction<Result>, options?: WithCycloneUIOptions & {
73
+ tokens?: undefined;
74
+ }): NextConfigFunction<Result extends Promise<NextConfig> ? Promise<NextConfig> : NextConfig>;
75
+ declare function withCycloneUI(nextConfig: NextConfigFunction, options: WithCycloneUIOptions): NextConfigFunction;
66
76
  export { WithCycloneUIOptions, withCycloneUI };
67
77
  //# sourceMappingURL=index.d.cts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;KA4BY,uBAAuB,QAAQ;;;;;;;;;;;;;;;EAezC,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkFK,cACd,aAAa,YACb,UAAU;EAAyB;IAClC;iBACa,cACd,YAAY,wBACZ,SAAS,uBACR,aAAa,QAAQ"}
1
+ {"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;KA4BY,uBAAuB,QAAQ;;;;;;;;;;;;;;;EAezC,SAAS;;KAGN,mBACH,eAAe,aAAa,QAAQ,cAClC,aAAa,QAAQ,gBACpB,eAAe;EAAW,eAAe;MAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoG/C,cACd,aAAa,YACb,UAAU;EAAyB;IAClC;iBACa,cACd,YAAY,wBACZ,SAAS,uBACR,aAAa,QAAQ;iBACR,cACd,YAAY,QAAQ,aACpB,UAAU,uBACT,QAAQ;iBACK,cAAc,eAAe,aAAa,QAAQ,aAChE,YAAY,mBAAmB,SAC/B,UAAU;EAAyB;IAClC,mBACD,eAAe,QAAQ,cAAc,QAAQ,cAAc;iBAE7C,cACd,YAAY,oBACZ,SAAS,uBACR"}
package/dist/index.d.mts CHANGED
@@ -22,6 +22,9 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
22
22
  */
23
23
  tokens?: BuildTamaguiConfigOptions["tokens"];
24
24
  };
25
+ type NextConfigFunction<Result extends NextConfig | Promise<NextConfig> = NextConfig | Promise<NextConfig>> = (phase: string, context: {
26
+ defaultConfig: NextConfig;
27
+ }) => Result;
25
28
  /**
26
29
  * Wrap a Next.js config with the setup Tamagui and Cyclone UI components need.
27
30
  *
@@ -34,6 +37,8 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
34
37
  *
35
38
  * With `tokens`, the Tamagui config is built from them first, so this returns
36
39
  * a promise, which Next.js accepts as the config export.
40
+ * Phase functions receive Next.js's original phase and default config and
41
+ * remain lazy; async functions and promised configs are resolved before setup.
37
42
  *
38
43
  * Turbopack builds don't run the Tamagui compiler. To optimize them, use the
39
44
  * Tamagui CLI: `tamagui build --target web ./src -- next build`.
@@ -54,7 +59,7 @@ type WithCycloneUIOptions = Partial<WithTamaguiProps> & {
54
59
  * export default withCycloneUI({}, { tokens: "tokens/**\/*.json" });
55
60
  * ```
56
61
  *
57
- * @param nextConfig - The Next.js config to extend.
62
+ * @param nextConfig - The Next.js config, promise, or phase function to extend.
58
63
  * @param options - The design `tokens`, plus options forwarded to
59
64
  * `@tamagui/next-plugin` (Webpack only).
60
65
  * @returns The extended Next.js config.
@@ -63,5 +68,10 @@ declare function withCycloneUI(nextConfig?: NextConfig, options?: WithCycloneUIO
63
68
  tokens?: undefined;
64
69
  }): NextConfig;
65
70
  declare function withCycloneUI(nextConfig: NextConfig | undefined, options: WithCycloneUIOptions): NextConfig | Promise<NextConfig>;
71
+ declare function withCycloneUI(nextConfig: Promise<NextConfig>, options?: WithCycloneUIOptions): Promise<NextConfig>;
72
+ declare function withCycloneUI<Result extends NextConfig | Promise<NextConfig>>(nextConfig: NextConfigFunction<Result>, options?: WithCycloneUIOptions & {
73
+ tokens?: undefined;
74
+ }): NextConfigFunction<Result extends Promise<NextConfig> ? Promise<NextConfig> : NextConfig>;
75
+ declare function withCycloneUI(nextConfig: NextConfigFunction, options: WithCycloneUIOptions): NextConfigFunction;
66
76
  export { WithCycloneUIOptions, withCycloneUI };
67
77
  //# sourceMappingURL=index.d.mts.map
package/dist/index.mjs CHANGED
@@ -1,2 +1,2 @@
1
- import{createRequire as e}from"node:module";import{join as t,relative as n}from"node:path";const r=(r,i,a)=>({...r,env:{TAMAGUI_TARGET:`web`,...r.env},turbopack:{...r.turbopack,resolveAlias:{"react-native":`react-native-web`,"react-native-svg":`@tamagui/react-native-svg`,...a&&{"@cyclone-ui/tokens/tamagui":`./${n(process.cwd(),a)}`},...r.turbopack?.resolveAlias}},webpack:(n,o)=>{let{withTamagui:s}=e(t(o.dir,`package.json`))(`@tamagui/next-plugin`),c=s({config:a??`@cyclone-ui/tokens/tamagui`,components:[`@tamagui/core`],appDir:!0,...i})(r).webpack(n,o);return a&&(c.resolve.alias[`@cyclone-ui/tokens/tamagui$`]=a),c}});function i(e={},{tokens:t,...n}={}){return t?import(`@cyclone-ui/theme-builder`).then(async({buildTamaguiConfig:e})=>e({tokens:t})).then(t=>r(e,n,t)):r(e,n)}export{i as withCycloneUI};
1
+ import{createRequire as e}from"node:module";import{join as t,relative as n}from"node:path";const r=(r,i,a)=>({...r,env:{TAMAGUI_TARGET:`web`,...r.env},turbopack:{...r.turbopack,resolveAlias:{"react-native":`react-native-web`,"react-native-svg":`@tamagui/react-native-svg`,...a&&{"@cyclone-ui/tokens/tamagui":`./${n(process.cwd(),a)}`},...r.turbopack?.resolveAlias}},webpack:(n,o)=>{let{withTamagui:s}=e(t(o.dir,`package.json`))(`@tamagui/next-plugin`),c=s({config:a??`@cyclone-ui/tokens/tamagui`,components:[`@tamagui/core`],appDir:!0,...i})(r).webpack(n,o);return a&&(c.resolve.alias[`@cyclone-ui/tokens/tamagui$`]=a),c}}),i=(e,{tokens:t,...n})=>e instanceof Promise?e.then(e=>i(e,{tokens:t,...n})):t?import(`@cyclone-ui/theme-builder`).then(async({buildTamaguiConfig:e})=>e({tokens:t})).then(t=>r(e,n,t)):r(e,n);function a(e={},t={}){return typeof e==`function`?(n,r)=>i(e(n,r),t):i(e,t)}export{a as withCycloneUI};
2
2
  //# sourceMappingURL=index.mjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.mjs","names":["extend","nextConfig","configPath","relative","createRequire","join","context","result","withTamagui","options","config","withCycloneUI","tokens","buildTamaguiConfig"],"sources":[],"mappings":""}
1
+ {"version":3,"file":"index.mjs","names":["extend","nextConfig","configPath","relative","createRequire","join","context","result","withTamagui","options","config","resolveConfig","tokens","buildTamaguiConfig","withCycloneUI","phase"],"sources":[],"mappings":""}
@@ -0,0 +1,94 @@
1
+ # Production navigation verification
2
+
3
+ This package is a framework integration and component library. The public fixture
4
+ under `test/fixture` provides representative routes; it has no authentication,
5
+ external services, mutable data, or application-specific cache policy.
6
+
7
+ ## Run
8
+
9
+ From the repository root:
10
+
11
+ ```sh
12
+ devenv shell -- pnpm --filter @cyclone-ui/nextjs exec playwright test
13
+ ```
14
+
15
+ Install the Playwright Chromium browser first, or set `CHROMIUM_PATH` to an
16
+ available executable. If the development environment's automatic package install
17
+ tries to reinstall already verified dependencies, disable only that hook:
18
+
19
+ ```sh
20
+ devenv -O languages.javascript.pnpm.install.enable:bool false shell -- pnpm --filter @cyclone-ui/nextjs exec playwright test
21
+ ```
22
+
23
+ The Playwright web server runs `test/production-server.mjs`, builds the local
24
+ fixture with Next.js 16.4.4, and serves the new artifact on port 3197. A listener
25
+ already using that port is an error; `reuseExistingServer` is disabled. Playwright
26
+ owns the server process group and cleanup. Builds and tests are awaited. There is
27
+ no remote artifact or separate deployment liveness check.
28
+
29
+ The runner enables `EXPOSE_TESTING_API=1` for **both build and start**. The fixture
30
+ config gates `experimental.exposeTestingApiInProductionBuild` on that variable.
31
+ This version reloads the config at startup, so omitting it from the server process
32
+ disables the document lock despite its presence in the build artifact. Never
33
+ enable this API for a user-facing production deployment.
34
+
35
+ ## Contracts
36
+
37
+ - Initial `/`: the heading, provider/theme script, styles and request-content
38
+ fallback are available; request content waits for the lock to release.
39
+ - `/` → “Second page” → `/second`: the destination shell and fallback are
40
+ visible while fresh request content waits. Scope assertions to the destination
41
+ because React may retain hidden content from the source route.
42
+ - Initial `/composition`: flat Page and Footer slots are rendered from a Server
43
+ Component; a neutral chart formatter executes in a cached Server Component.
44
+ Their visible shell renders before fresh content. Theme changes hydrate cleanly.
45
+ A separate normal-streaming check preserves typed input and focus when fresh
46
+ content arrives; the testing API's hard-load release refreshes the route, so
47
+ that artificial refresh is not used to measure client state preservation.
48
+ - Initial `/calendar-probe`: the surrounding shell prerenders with the calendar's
49
+ sized loading fallback in its static HTML. The current-date calendar resolves
50
+ and becomes interactive after hydration, without blocking the page shell.
51
+ - Initial `/charts-probe`: loading and loaded BarChart and ComposedChart variants
52
+ build and hydrate without render-time clock errors or random SVG mismatches.
53
+ Loaded variants exercise the normal bar-grow animation path.
54
+ - `/` → “Default prefetch” → `/search?q=default`: the shared search shell is
55
+ prefetched; URL-dependent results and fresh content wait for navigation.
56
+ - `/` → “Prefetch results” → `/search?q=prefetched`: `prefetch={true}` includes
57
+ the cached URL-dependent results; fresh content still waits. This is a fixture
58
+ policy, not a default imposed on Cyclone links or consuming applications.
59
+ - The existing theme regression script verifies persisted light/dark preferences,
60
+ forced themes, system changes, cookies, delayed hydration, navigation, and
61
+ first-paint CSS with hydration bundles blocked.
62
+
63
+ The fixtures use immutable inline data with the framework's default cache profile;
64
+ there are no writers to invalidate. Reusable production data must use a lifetime
65
+ and invalidation policy selected by its owning application.
66
+
67
+ ## Trust and iteration
68
+
69
+ Use `instant()` from `@next/playwright` on the same release as `next`. Every locked
70
+ test with deferred content asserts that it is absent during the lock and present
71
+ after release. A missing testing API therefore fails the test. Tests have no
72
+ retries, timing budgets or manual prefetch warming.
73
+
74
+ Confirm the same direct load or link reaches its completed destination without
75
+ the lock when authoring a new contract, then remove that temporary scaffold.
76
+ Rebuild after any source or config change. Compare the locked result with only
77
+ the relevant export/boundary/prefetch change removed, then reapply and run the
78
+ complete suite. Do not manufacture failures by disabling unrelated prefetching.
79
+
80
+ Test context: public; no authentication, feature flags, account roles, localization
81
+ or seeded database. Browser contexts are fresh per test and default to a light
82
+ system preference. The theme script explicitly seeds saved dark mode. Known drift:
83
+ none for these fixture contracts. These tests verify source integration, not a
84
+ published package installed by the Cyclone CLI or every consuming application's
85
+ routes. Inspect package builds separately for preserved client directives.
86
+
87
+ Verified differentials: Calendar's original render-time current-date read and
88
+ the original chart mount timestamps fail production prerendering. Restoring
89
+ their boundaries and effect-based timestamps allows the fixture to build. Removing
90
+ only `prefetch={true}` from “Prefetch results” leaves the shared search shell
91
+ available, but the cached URL results assertion fails under the lock. Restoring
92
+ that link policy restores the passing contract. Unlocked checks for both search
93
+ links and the composition route reached their completed UI before the temporary
94
+ baseline tests were removed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cyclone-ui/nextjs",
3
- "version": "0.0.15",
3
+ "version": "0.0.16",
4
4
  "type": "module",
5
5
  "description": "A Next.js config wrapper and root provider that set up Tamagui and Cyclone UI components in Next.js applications.",
6
6
  "repository": {
@@ -45,12 +45,12 @@
45
45
  "module": "./dist/index.mjs",
46
46
  "types": "./dist/index.d.cts",
47
47
  "dependencies": {
48
- "@cyclone-ui/theme-builder": "0.0.33",
48
+ "@cyclone-ui/theme-builder": "0.0.34",
49
49
  "@tamagui/next-theme": "3.0.13"
50
50
  },
51
51
  "peerDependencies": {
52
- "@cyclone-ui/state": "0.0.45",
53
- "@cyclone-ui/tokens": "0.3.32",
52
+ "@cyclone-ui/state": "0.0.46",
53
+ "@cyclone-ui/tokens": "0.3.33",
54
54
  "@tamagui/core": "3.0.13",
55
55
  "@tamagui/next-plugin": "3.0.13",
56
56
  "@tamagui/react-native-svg": "3.0.13",
@@ -65,8 +65,10 @@
65
65
  "react-native": { "optional": true }
66
66
  },
67
67
  "devDependencies": {
68
- "@cyclone-ui/state": "0.0.45",
69
- "@cyclone-ui/tokens": "0.3.32",
68
+ "@cyclone-ui/state": "0.0.46",
69
+ "@cyclone-ui/tokens": "0.3.33",
70
+ "@next/playwright": "16.4.4",
71
+ "@playwright/test": "1.64.1",
70
72
  "@powerlines/plugin-tsdown": "^0.1.619",
71
73
  "@tamagui/core": "3.0.13",
72
74
  "@tamagui/next-plugin": "3.0.13",
@@ -77,5 +79,5 @@
77
79
  "react-native-web": "0.19.12"
78
80
  },
79
81
  "publishConfig": { "access": "public" },
80
- "gitHead": "2aea79c16eef482fc6e86a38189c8e404596803c"
82
+ "gitHead": "b8f9ad1a52c5ca88a43e0cf52b88d9751cb58303"
81
83
  }