docs: improve docs about prisma-client imports

content/200-orm/100-prisma-schema/10-overview/02-data-sources.mdx

@@ -4,8 +4,6 @@ metaTitle: 'Data sources (Reference)'
 metaDescription: 'Data sources enable Prisma to connect to your database. This page explains how to configure data sources in your Prisma schema.'
 ---
 
-<TopBlock>
-
 A data source determines how Prisma ORM connects to your database, and is represented by the [`datasource`](/orm/reference/prisma-schema-reference#datasource) block in the Prisma schema. The following data source uses the `postgresql` provider and includes a connection URL:
 
 ```prisma
@@ -22,8 +20,6 @@ A Prisma schema can only have _one_ data source. However, you can:
 
 > **Note**: Multiple provider support was removed in 2.22.0. Please see [Deprecation of provider array notation](https://github.com/prisma/prisma/issues/3834) for more information.
 
-</TopBlock>
-
 ## Securing database connections
 
 Some data source `provider`s allow you to configure your connection with SSL/TLS, and provide parameters for the `url` to specify the location of certificates.

content/200-orm/100-prisma-schema/10-overview/03-generators.mdx

@@ -92,7 +92,7 @@ If you use macOS ARM64 (`darwin-arm64`), then the binary file that was compiled
 
 The new `prisma-client` generator offers greater control and flexibility when using Prisma ORM across different JavaScript environments (such as ESM, Bun, Deno, ...).
 
-It generates Prisma Client into a custom directory in your application's codebase that's specified via the `output` field on the `generator` block. This gives you full visibility and control over the generated code. It also [splits](#output-splitting-and-importing-types) the generated Prisma Client library into multiple files.
+It generates Prisma Client into a custom directory in your application's codebase that's specified via the `output` field on the `generator` block. This gives you full visibility and control over the generated code. It also [splits](#importing-types) the generated Prisma Client library into multiple files.
 
 This generator ensures you can bundle your application code exactly the way you want, without relying on hidden or automatic behaviors.
 
@@ -237,23 +237,12 @@ Below are the options for the `prisma-client` generator:
 
 :::
 
-### Output splitting and importing types
+### Importing types
 
-The `prisma-client-js` generator used to generate all typings into a single `index.d.ts` file, which could lead to [slowing down editors](https://github.com/prisma/prisma/issues/4807) (e.g. breaking auto-complete) with large schemas.
+The new `prisma-client` generator creates individual `.ts` files which allow for a more fine granular import of types. This can improve compile and typecheck performance and be useful for tree-shaking, too. 
+You can still use the top level barrel files that export all types through a single import.
 
-The new `prisma-client` generator now splits the generated Prisma Client library into multiple files and thus avoids the problems of a single, large output file.
-
-**Before** (`prisma-client-js`)
-
-```
-generated/
-└── prisma
-    ├── client.ts
-    ├── index.ts # -> this is split into multiple files in 6.7.0
-    └── libquery_engine-darwin.dylib.node
-```
-
-**After** (`prisma-client`)
+The overall structure of the generated output looks like this:
 
 ```
 generated/
@@ -263,15 +252,127 @@ generated/
     ├── commonInputTypes.ts
     ├── enums.ts
     ├── internal
-    │   ├── class.ts
-    │   ├── prismaNamespace.ts
-    │   └── prismaNamespaceBrowser.ts
+    │   ├── ...
     ├── models
     │   ├── Post.ts
     │   └── User.ts
     └── models.ts
 ```
 
+#### `client.ts`
+
+For use in your server code. 
+
+- Provides access to the `PrismaClient` instance and all model and utility types. 
+- Provides best compatibility with the `prisma-client-js` generated output.
+- Contains transitive dependencies on server only-packages, so cannot be used in browser contexts.
+
+Example:
+
+```ts
+import { Prisma, type Post, PrismaClient } from "./generated/prisma/client"
+```
+
+#### `browser.ts`
+
+For using types in your frontend (i.e. code that runs in the browser). 
+
+- Contains no transitive dependencies on Node.js or other server-only packages. 
+- Contains no real `PrismaClient` constructor.
+- Contains all model and enum types and values.
+- Provides access to various utilities like `Prisma.JsonNull` and `Prisma.Decimal`.
+- Available since `v6.16.0`.
+
+:::note
+
+The old `prisma-client-js` generator created a `node_modules` package and used export maps to dynamically provide a browser compatible export of the generated Prisma Client library. As the new `prisma-client` generator creates direct TypeScript source code and no `package.json` file anymore, this approach is not possible. Hence you need to be explicit about your imports and whether things run on server or client! 
+
+You can still wrap the generated code in a package and use a similar approach as with `prisma-client-js` on your own.
+
+:::
+
+Example:
+
+```ts
+import { Prisma, type Post } from "./generated/prisma/browser"
+```
+
+#### `enums.ts`
+
+Isolated access to user defined enum types and values.
+
+- Contains no transitive dependencies and is very slim.
+- Can be used on backend and frontend.
+- Prefer this for optimal tree shaking and typecheck performance when accessing enums.
+
+Example:
+
+```ts
+import { MyEnum } from "./generated/prisma/enums"
+```
+
+#### `models.ts`
+
+Isolated access to all model types.
+
+- Can be used on backend and frontend.
+- Contains all models including their derived utility types like `<ModelName>WhereInput` or `<ModelName>UpdateInput>`.
+
+:::note
+
+Plain model types are exposed here as `<ModelName>Model` (e.g. `PostModel`). This is in contrast to the exposed name in `client.ts` and `browser.ts` which is simply `<ModelName>` (e.g. `Post`).
+
+This is necessary due to internal constraints to avoid potential naming conflicts with internal types.
+
+:::
+
+Example:
+
+```ts
+import type { UserModel, PostModel, PostWhereInput, UserUpdateInput } from "./generated/prisma/models"
+```
+
+
+#### `models/<ModelName>.ts`
+
+Isolated access to the types for an individual model.
+
+- Can be used on backend and frontend.
+- Contains the models including its derived utility types like `<ModelName>WhereInput` or `<ModelName>UpdateInput>`.
+
+:::note
+
+The plain model type is exposed here as `<ModelName>Model` (e.g. `PostModel`).
+
+:::
+
+Example:
+
+```ts
+import type { UserModel, UserWhereInput, UserUpdateInput } from "./generated/prisma/models/User"
+```
+
+
+#### `commonInputTypes.ts`
+
+Provides shared utility types that you should rarely directly need.
+
+Example: 
+
+```ts
+import type { IntFilter } from "./generated/prisma/commonInputTypes"
+```
+
+#### `internal/*`
+
+:::warning
+
+Do not directly import from these files! They are not part of the stable API of the generated code and can change at any time in breaking ways.
+
+Usually anything you might need from there is exposed via `browser.ts` or `client.ts` under the `Prisma` namespace.
+
+:::
+
 ### Breaking changes from `prisma-client-js`
 
 - Requires an `output` path on the `generator` block