create-prisma-php-app 5.1.0-alpha.3 → 5.1.0-alpha.30

package/README.md

@@ -36,10 +36,14 @@ If you are using XAMPP on Windows, enabling `extension=zip` in `php.ini` is reco
 Prisma PHP brings together the core pieces needed to build full-stack PHP apps:
 
 - **Native PHP + modern reactivity** with PulsePoint
+- **Direct RPC from the frontend** with `pp.rpc(...)` calling `#[Exposed]` PHP functions — JSON in, JSON out, SSE streaming when the function yields, and framework failures reported as real HTTP statuses
+- **Named sockets for realtime** with `pp.socket(...)` — long-lived bidirectional messaging (chat, presence, live feeds) served by a Ratchet-based socket server with per-socket auth, origin checks, and rate limits
 - **PHPX component system** for reusable UI composition
 - **Prisma PHP ORM** for schema-first, type-safe database access
 - **Built-in authentication patterns** for sessions, route protection, RBAC, credentials auth, and provider login
+- **Hardened request pipeline** with double-submit CSRF (`pp_csrf` cookie family), origin validation, content-type checks, and per-function rate limiting
 - **File-based routing** with clear route file conventions
+- **App-level test suite** with PHPUnit in a root `tests/` directory, run with `npm run test`, feature-aware via `prisma-php.json`
 - **CLI scaffolding** for new apps, starter kits, and optional features
 - **Flexible deployment options** for local development and production workflows
 
@@ -117,7 +121,10 @@ Use these docs as the main entry points for common work:
 - `project-structure.md` for project structure, route placement, and file conventions
 - `layouts-and-pages.md` for pages, layouts, nested routes, and dynamic routes
 - `components.md` for PHPX components, props, children, fragments, icons, buttons, and composition
-- `fetching-data.md` for `pp.fetchFunction(...)`, `#[Exposed]`, and interactive backend flows
+- `fetching-data.md` for `pp.rpc(...)`, `#[Exposed]`, streaming, and the RPC error contract
+- `websocket.md` for named sockets, `pp.socket(...)`, `SocketRegistry`, and the realtime wire contract
+- `bootstrap-runtime.md` for the runtime init order, PulsePoint wire headers, and the `pp_csrf` CSRF contract
+- `testing.md` for the root `tests/` directory, `npm run test`, and feature-gated tests
 - `prisma-php-orm.md` for Prisma ORM, `schema.prisma`, migrations, and generated PHP classes
 - `authentication.md` for auth strategy, sessions, RBAC, credentials auth, and provider flows
 - `file-manager.md` for uploads, `multipart/form-data`, `$_FILES`, and `PP\FileManager\UploadFile`
@@ -152,13 +159,15 @@ For task-specific route decision rules and framework generation rules, read `AGE
 
 ## PulsePoint and Frontend Reactivity
 
-Prisma PHP uses PulsePoint for browser-side reactivity.
+Prisma PHP uses PulsePoint for browser-side reactivity and as the wire between the page and PHP.
 
 When working with runtime features such as:
 
 - `pp.state`
 - `pp.effect`
 - `pp.ref`
+- `pp.rpc` for frontend-to-PHP calls (with streaming, uploads, and redirects)
+- `pp.socket` for named-socket realtime messaging
 - `pp-for`
 - `pp-spread`
 - `pp-ref`
@@ -179,11 +188,23 @@ prisma-php-project/
 ├── public/            # public entry point and assets
 ├── settings/          # project configuration
 ├── src/               # application source code
+├── tests/             # app-level PHPUnit tests (npm run test)
 ├── package.json       # frontend/dev scripts
 ├── composer.json      # PHP dependencies
+├── phpunit.xml        # test suite configuration
 └── prisma-php.json    # Prisma PHP project capability manifest
 ```
 
+## Testing
+
+App tests live in the root `tests/` directory and run with:
+
+```bash
+npm run test
+```
+
+The suite runs PHPUnit on the PHP binary configured in `prisma-php.json`, uses a deterministic test environment (the real `.env` is never loaded), and is feature-aware: tests for optional features such as WebSocket skip cleanly when the feature is disabled in `prisma-php.json`. Read `testing.md` in the installed docs and the project's `tests/README.md` for the full contract.
+
 ## Updating Existing Projects
 
 When enabling features or syncing framework-managed project files:

package/dist/.github/copilot-instructions.md

@@ -7,13 +7,14 @@
 - Treat `node_modules/prisma-php/dist/docs` as framework reference docs that teach AI how Prisma PHP works. The presence of a page in that docs folder does not mean the current workspace has that feature enabled.
 - Read the matching doc in `node_modules/prisma-php/dist/docs` before generating or editing framework-specific Prisma PHP code.
 - Expect `AGENTS.md` in the project root and keep it aligned with the installed Prisma PHP docs contract.
-- In the Prisma PHP package source repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, any `.github/instructions/**/*.instructions.md`, and `dist/docs` aligned so the published docs remain correct after install.
+- In the Prisma PHP package source repo, keep the source-repo `AGENTS.md`, `.github/copilot-instructions.md`, any `.github/instructions/**/*.instructions.md`, and source-repo `dist/docs` aligned so the published docs remain correct after install. In consumer apps, the installed docs path is `node_modules/prisma-php/dist/docs`.
 - Do not assume installed consumer apps also ship a root `.github/copilot-instructions.md` unless the generator explicitly creates one.
 - If `.github/instructions/**/*.instructions.md` exists, treat those files as workspace-local task instructions for third-party libraries, component systems, icon packs, and other implementation-specific rules.
 - Before generating or editing code, inspect `.github/instructions/` and read any `*.instructions.md` files that match the current task, named library, target files, or implementation surface.
-- Keep every `dist/docs/*.md` page AI-discoverable on its own: the frontmatter description and opening section should clearly say when agents should read that file and which adjacent docs to consult next.
+- In the Prisma PHP package source repo, keep every `dist/docs/*.md` page AI-discoverable on its own. In consumer apps, those installed docs live at `node_modules/prisma-php/dist/docs/*.md`. The frontmatter description and opening section should clearly say when agents should read that file and which adjacent docs to consult next.
 - When a task maps to an optional feature such as `backendOnly`, `swaggerDocs`, `typescript`, `websocket`, or `mcp`, inspect `./prisma-php.json` first, then read the matching docs page to learn the implementation contract.
-- When docs and project files still leave a runtime gap, inspect the narrow core file that owns the behavior: `TemplateCompiler.php` for HTML fragment compilation and route root scoping, `ImportComponent.php` for imported partials, `MainLayout.php` for metadata and head/footer scripts, `PrismaPHPSettings.php` plus generated settings JSON for component and route maps, `Request.php` for request handling, `Validator.php`/`Rule.php` for validation, and feature-specific files such as `UploadFile.php`, `Mailer.php`, or `Streaming/SSE.php`.
+- When docs and project files still leave a runtime gap, inspect the narrow core file that owns the behavior: `TemplateCompiler.php` for HTML fragment compilation and route root scoping, `PHPX.php` plus `TwMerge.php` for PHPX class composition and frontend `twMerge(...)` emission, `ImportComponent.php` for imported partials, `MainLayout.php` for metadata and head/footer scripts, `PrismaPHPSettings.php` plus generated settings JSON for component and route maps, `Request.php` for request handling, `Validator.php`/`Rule.php` for validation, and feature-specific files such as `UploadFile.php`, `Mailer.php`, or `Streaming/SSE.php`.
+- When validation or rule-builder syntax is involved, read `node_modules/prisma-php/dist/docs/validator.md` first. If method shape is still unclear after that, inspect `vendor/tsnc/prisma-php/src/Rule.php` to confirm which `Rule` methods are static entry points and which methods must be chained on a builder instance.
 
 ## Workspace Task Instructions
 
@@ -28,9 +29,11 @@
 - Keep `src/app` focused on route files, layouts, handlers, and route-scoped partials.
 - Prefer `src/Components` for reusable application UI components shared across pages or layouts.
 - Keep reusable non-UI code such as services, auth, middleware, Prisma classes, and helpers in `src/Lib`.
+- Treat route-private folders such as `src/app/<route>/_components` as an implementation detail for files that stay owned by that route only.
 - Treat `./public/uploads` as the default local public upload directory for file uploads.
 - Treat generated component libraries such as `src/Lib/PHPXUI` and `src/Lib/PPIcons` as library-specific surfaces governed by their manifests and `.github/instructions/*.instructions.md` files.
 - If a partial starts as route-local but becomes shared across the app, move it from `src/app` to `src/Components`.
+- Do not default to creating `src/app/<route>/_components` for app-owned section components such as `HeroSection`, `FormSection`, or `SidebarSection`; prefer `src/Components` unless the user explicitly wants route-local colocation and the files are truly private to that route.
 - Suggest this structure by default when helping users organize growing Prisma PHP apps.
 
 ## Component Tag Contract
@@ -43,6 +46,14 @@
 - Use mustache values for reactive props, such as `selected-date="{selectedDate}"` and `on-date-select="{setSelectedDate}"`.
 - Write component examples as HTML-first Prisma PHP markup using the current `x-` tag contract.
 
+## Tailwind Merge Contract
+
+- In Tailwind-enabled Prisma PHP apps, Tailwind utility conflict resolution belongs to the frontend `twMerge(...)` runtime helper.
+- `getMergeClasses(...)` and `PP\PHPX\TwMerge::merge(...)` emit frontend `twMerge(...)` expressions for the browser runtime to resolve.
+- `twMerge(...)` is an app-level browser helper, not a PulsePoint built-in.
+- In TypeScript-enabled apps, Prisma PHP registers that helper from `ts/main.ts`; in non-TypeScript Tailwind apps it is registered from `public/js/main.js` (importing `public/js/tailwind-merge.mjs`). Use `typescript.md` for route usage and `components.md` for PHPX usage.
+- Keep Tailwind merge decisions on the frontend runtime instead of trying to finalize conflicting utility classes in PHP.
+
 ## Framework-Managed Package Scripts
 
 - Prisma PHP can generate `package.json` scripts for BrowserSync, Tailwind, TypeScript, WebSocket, MCP, Swagger docs, and related helpers.
@@ -50,7 +61,7 @@
 - Do not default to telling users to run `npm run tailwind`, `npm run tailwind:build`, `npm run ts:watch`, or `npm run ts:build` after routine file changes, because those are usually orchestrated through the generated top-level scripts.
 - Use `npm run websocket` or `npm run mcp` only when isolating local runtime startup, debugging, or when the project's scripts show those services are not already covered by the normal development flow.
 - Use `npm run create-swagger-docs` only when Swagger or OpenAPI output must be intentionally generated or refreshed.
-- When package-script behavior matters, read `dist/docs/commands.md` first and inspect the actual `package.json` in the target project before assuming which scripts exist.
+- When package-script behavior matters, read `node_modules/prisma-php/dist/docs/commands.md` first and inspect the actual `package.json` in the target project before assuming which scripts exist.
 
 ## BrowserSync URL Source Of Truth
 
@@ -79,6 +90,7 @@
 ## Authentication Route Strategy
 
 - Prisma PHP defaults to public routes.
+- Auth classes are app-owned under `src/Lib/Auth` in the `Lib\Auth` namespace: `use Lib\Auth\Auth;`, `use Lib\Auth\AuthConfig;`, `use Lib\Auth\AuthRole;` — never `PP\Auth\...`.
 - Choose the route privacy strategy at the start of the app, before creating most routes.
 - If the app will have many public pages, keep the public-default strategy.
 - If the app will have only a few public entry points and most routes should require login, use the private-default strategy.
@@ -91,20 +103,32 @@
 ## PulsePoint-First Frontend Rules
 
 - In full-stack Prisma PHP apps, treat PulsePoint as the primary JavaScript authoring model for frontend behavior.
-- For page-local interactivity, prefer `index.php` or nested `layout.php` with a plain inline `<script>` that contains PulsePoint state and functions directly, and use `pp.fetchFunction(...)` for backend calls.
+- For page-local interactivity, prefer `index.php` or nested `layout.php` with a plain inline `<script>` that contains PulsePoint state and functions directly, and use `pp.rpc(...)` for backend calls.
 - Do not wrap inline PulsePoint code in `DOMContentLoaded`, IIFEs, manual `pp.mount()` calls, or custom scoping/bootstrap helpers. Prisma PHP scopes the component boundary and runs the script for you.
 - Reserve plain browser JavaScript or TypeScript modules for reusable helpers in `ts/`, third-party libraries, low-level browser APIs, or behavior that does not belong inside a PulsePoint component boundary.
-- Use `pp-style` for template-driven inline CSS, `pp-spread="{...attrs}"` for dynamic attribute objects, `pp-for` only on `<template>`, and plain `key` for keyed diffing.
+- Do not treat app-registered helpers such as `twMerge(...)` as PulsePoint built-ins; only use them after the relevant Prisma PHP feature flag and entry-file docs confirm they exist.
+- Use `pp-style` whenever inline CSS contains `{...}` interpolation or any other template-driven/reactive value, reserve plain `style` for fully static inline CSS, use `pp-spread="{...attrs}"` for dynamic attribute objects, keep `pp-for` only on `<template>`, and use plain `key` for keyed diffing.
+- Do not generate reactive inline CSS inside a plain `style` attribute such as `style="width: {progress}%";` use `pp-style="width: {progress}%";` instead so editor CSS validation does not flag the source markup as invalid.
 - Use `pp.ref(...)`, `pp-ref`, `pp.portal(...)`, `pp.createContext(...)`, `Context.Provider`, and `pp.context(...)` according to `pulsepoint.md`.
 - Use `value`, `defaultvalue`, and `defaultchecked` form bindings according to `pulsepoint.md`; do not author internal `data-pp-*` runtime attributes.
 
+## Runtime Wire Contract
+
+- `pp.rpc(functionName, data?, optionsOrAbort?)` is the frontend-to-PHP call API.
+- Every function called through `pp.rpc(...)` must be marked `#[Exposed]` on the PHP side.
+- Framework-level RPC failures (unknown function, auth, roles, CSRF, origin, content type, rate limit, server error) arrive as HTTP error statuses with an `{"error": "..."}` JSON body and reject the `pp.rpc(...)` promise; wrap calls in `try/catch` when the UI reacts to failures. Return routine validation feedback as structured data instead of throwing. Throwing `InvalidArgumentException` in an exposed function is the sanctioned validation crossover: its message reaches the caller as a 400.
+- Streamed responses: an exposed function that yields streams SSE `data:` lines; consume them with `onStream`, `onStreamError`, and `onStreamComplete`.
+- CSRF: the runtime reads the `pp_csrf` cookie family (`pp_csrf_<port>` in development, `pp_csrf` otherwise), managed server-side by `PP\Security\Csrf` and signed with `FUNCTION_CALL_SECRET`.
+- Realtime: use `pp.socket(name, args, handlers)` (named sockets) for long-lived bidirectional flows. Server handlers are registered with `SocketRegistry::register(...)` in `src/Lib/Websocket/sockets.php`; the wire is one endpoint (`/__pulsepoint/ws?name=...`), arguments as the first JSON frame, JSON frames both ways, and `{"error": "..."}` reserved for failures. Do not generate raw `new WebSocket(...)` wiring for app realtime work.
+- Read `node_modules/prisma-php/dist/docs/fetching-data.md`, `bootstrap-runtime.md`, and `websocket.md` for the full contracts.
+
 ## Route File Conventions
 
 - For PulsePoint-aware `index.php` and nested `layout.php`, keep file order as PHP first, then one parent HTML element as the route boundary, then the visible route content inside that boundary, and keep the PulsePoint `<script>` as the last child of that boundary root.
 - `index.php` and nested `layout.php` must render a single parent HTML element. Treat that root like a component boundary rather than loose sibling markup.
 - If the visible page or layout content should stay inside a semantic element such as `<main>`, `<section>`, or `<article>`, wrap it in a neutral parent such as `<div>` so the route boundary can still own the `<script>`.
 - For pages and nested layouts, author a plain single root element and let Prisma PHP inject the PulsePoint `pp-component` scope automatically.
-- Author plain `<script>` tags inside that boundary root when PulsePoint is needed, usually as a sibling of the visible content container instead of nesting the script inside the semantic content element by default. Put the PulsePoint code at the top level of that script. Do not manually add `type="text/pp"`, `DOMContentLoaded` wrappers, IIFEs, or manual bootstrap code; Prisma PHP normalizes the script contract for the runtime.
+- Author plain `<script>` tags inside that boundary root when PulsePoint is needed, usually as a sibling of the visible content container instead of nesting the script inside the semantic content element by default. Put the PulsePoint code at the top level of that script. Never put a `type` attribute on a component script — the runtime only recognizes untyped scripts. Do not add `DOMContentLoaded` wrappers, IIFEs, or manual bootstrap code.
 - Do not leave the route `<script>` outside the route boundary.
 - Only the root `layout.php` should define `<html>`, `<head>`, and `<body>`. When PulsePoint is present, keep `MainLayout::$children;` and any `<script>` inside one clear wrapper.
 
@@ -113,32 +137,55 @@
 - Distinguish PHPX class components from `ImportComponent` partials.
 - `ImportComponent` partials must output exactly one root element because Prisma PHP uses that root as the imported component boundary and serializes props there.
 - Do not manually add `pp-component` inside `ImportComponent` partial source; Prisma PHP injects it there.
-- When imported partials need PulsePoint logic, keep the `<script>` inside that same root element and author it as a plain `<script>` tag without `type="text/pp"`, DOM-ready wrappers, or manual bootstrap code.
+- When imported partials need PulsePoint logic, keep the `<script>` inside that same root element and author it as a plain `<script>` tag with no `type` attribute (the runtime ignores typed scripts), without DOM-ready wrappers or manual bootstrap code.
+
+## Validation Rules
+
+- Use `PP\Validator` as the backend validation and normalization layer.
+- Prefer the `Rule` builder for rule-based validation.
+- Start `Rule` builders with `Rule::required()`, `Rule::optional()`, or `Rule::make()`.
+- Chain rule methods such as `->min(...)`, `->max(...)`, `->email()`, and `->regex(...)` on that builder instance.
+- Do not generate static calls such as `Rule::max(80)` or `Rule::email()`.
+- For optional constrained fields, use `Rule::optional()->max(80)` or `Rule::make()->max(80)`.
+- Validate in PHP even when the frontend already performs local checks.
+- Return structured validation results for expected failures instead of treating routine invalid input as an uncaught exception.
+- When internals matter, inspect `vendor/tsnc/prisma-php/src/Validator.php` and `vendor/tsnc/prisma-php/src/Rule.php`.
+
+## Testing Rules
+
+- App tests live in the root `tests/` directory and run with `npm run test` (PHPUnit via `settings/run-tests.ts`, using the PHP binary from `prisma-php.json`). Narrow runs with `npm run test -- --filter <NameOrMethod>`.
+- When adding or changing app behavior with logic worth protecting (exposed-function validation, socket handlers, auth rules, `src/Lib` helpers), add or update the matching `tests/*Test.php` in the same change and run `npm run test` before declaring the work done.
+- Tests cover app-level code and the wire contracts the app depends on; do not test Prisma PHP framework internals from the app suite.
+- Tests of optional features (`websocket`, `mcp`, `swaggerDocs`, `prisma`, ...) must guard on the `prisma-php.json` flag via the `Tests\Support\RequiresFeature` trait (`$this->requireFeature('websocket')` as the first line of `setUp()`), so a disabled feature skips cleanly instead of fataling on missing scaffold classes. Core surfaces (CSRF, wire headers, auth) are never gated.
+- `tests/bootstrap.php` sets a deterministic env (no real `.env`); shared fakes live in `tests/Support` (`Tests\Support\...`). Socket wire tests use `Tests\Support\FakeConnection` and assert frames plus close codes.
+- Read `node_modules/prisma-php/dist/docs/testing.md` and the project's `tests/README.md` before writing tests.
 
 ## Relevant Docs
 
-- Project structure and feature placement: `dist/docs/project-structure.md`
-- CLI project creation and update commands: `dist/docs/commands.md`
-- First-time project installation and local setup: `dist/docs/installation.md`
-- Existing-project upgrades and feature refreshes: `dist/docs/upgrading.md`
-- TypeScript frontend tooling, the `typescript` flag, and `ts/main.ts` registration: `dist/docs/typescript.md`
-- Backend-only API usage and `backendOnly`: `dist/docs/backend-only.md`
-- Route and layout structure: `dist/docs/layouts-and-pages.md`
-- AI integration, provider-backed chat, streaming, and MCP boundary: `dist/docs/get-started-ia.md`
-- Data loading, `#[Exposed]`, and SSE streaming: `dist/docs/fetching-data.md`
-- Bootstrap flow, runtime init order, request initialization, and function-call protection: `dist/docs/bootstrap-runtime.md`
-- PulsePoint runtime rules: `dist/docs/pulsepoint.md`
-- Component and `ImportComponent` rules: `dist/docs/components.md`
-- Cache behavior and `CacheHandler`: `dist/docs/caching.md`
-- Validation rules: `dist/docs/validator.md`
-- Prisma ORM schema, migrations, and generated PHP classes: `dist/docs/prisma-php-orm.md`
-- Environment variables and `PP\Env` usage: `dist/docs/env.md`
-- File uploads and file manager behavior: `dist/docs/file-manager.md`
-- Email and SMTP workflows: `dist/docs/email.md`
-- WebSocket and realtime behavior: `dist/docs/websocket.md`
-- MCP server and tool rules: `dist/docs/mcp.md`
-- Authentication: `dist/docs/authentication.md`
-- Error handling, expected failures, and route error files: `dist/docs/error-handling.md`
-- Metadata and icons: `dist/docs/metadata-and-og-images.md`
-- API-style handlers and webhooks: `dist/docs/route-handlers.md`
-- Swagger/OpenAPI generation and `swaggerDocs`: `dist/docs/swagger-docs.md`
+- Project structure and feature placement: `node_modules/prisma-php/dist/docs/project-structure.md`
+- CLI project creation and update commands: `node_modules/prisma-php/dist/docs/commands.md`
+- First-time project installation and local setup: `node_modules/prisma-php/dist/docs/installation.md`
+- Existing-project upgrades and feature refreshes: `node_modules/prisma-php/dist/docs/upgrading.md`
+- TypeScript frontend tooling, the `typescript` flag, and `ts/main.ts` registration: `node_modules/prisma-php/dist/docs/typescript.md`
+- Backend-only API usage and `backendOnly`: `node_modules/prisma-php/dist/docs/backend-only.md`
+- Route and layout structure: `node_modules/prisma-php/dist/docs/layouts-and-pages.md`
+- AI integration, provider-backed chat, streaming, and MCP boundary: `node_modules/prisma-php/dist/docs/get-started-ia.md`
+- Data loading, `#[Exposed]`, and SSE streaming: `node_modules/prisma-php/dist/docs/fetching-data.md`
+- Bootstrap flow, runtime init order, request initialization, and function-call protection: `node_modules/prisma-php/dist/docs/bootstrap-runtime.md`
+- PulsePoint runtime rules: `node_modules/prisma-php/dist/docs/pulsepoint.md`
+- Component and `ImportComponent` rules: `node_modules/prisma-php/dist/docs/components.md`
+- Frontend Tailwind class composition and `twMerge(...)`: `node_modules/prisma-php/dist/docs/components.md`, `node_modules/prisma-php/dist/docs/typescript.md`, and `node_modules/prisma-php/dist/docs/layouts-and-pages.md`
+- Cache behavior and `CacheHandler`: `node_modules/prisma-php/dist/docs/caching.md`
+- Validation rules: `node_modules/prisma-php/dist/docs/validator.md`
+- Prisma ORM schema, migrations, and generated PHP classes: `node_modules/prisma-php/dist/docs/prisma-php-orm.md`
+- Environment variables and `PP\Env` usage: `node_modules/prisma-php/dist/docs/env.md`
+- File uploads and file manager behavior: `node_modules/prisma-php/dist/docs/file-manager.md`
+- Email and SMTP workflows: `node_modules/prisma-php/dist/docs/email.md`
+- WebSocket and realtime behavior: `node_modules/prisma-php/dist/docs/websocket.md`
+- MCP server and tool rules: `node_modules/prisma-php/dist/docs/mcp.md`
+- Authentication: `node_modules/prisma-php/dist/docs/authentication.md`
+- Error handling, expected failures, and route error files: `node_modules/prisma-php/dist/docs/error-handling.md`
+- Metadata and icons: `node_modules/prisma-php/dist/docs/metadata-and-og-images.md`
+- API-style handlers and webhooks: `node_modules/prisma-php/dist/docs/route-handlers.md`
+- Swagger/OpenAPI generation and `swaggerDocs`: `node_modules/prisma-php/dist/docs/swagger-docs.md`
+- App test suite, `tests/` layout, and `npm run test`: `node_modules/prisma-php/dist/docs/testing.md`

package/dist/AGENTS.md

@@ -35,7 +35,8 @@ Important rules:
 - expect `./AGENTS.md` at the project root
 - when the installed docs and a habit from another framework conflict, follow Prisma PHP
 - when a workspace instruction file and the general Prisma PHP docs both apply, follow both; keep `./prisma-php.json` as the source of truth for feature enablement and prefer the most specific matching instruction for library- or file-scoped implementation details
-- when updating Prisma PHP package/docs sources, keep `AGENTS.md` and `dist/docs` aligned for consumer apps; if the Prisma PHP package source repo also maintains `.github/copilot-instructions.md` or `.github/instructions/**/*.instructions.md`, keep those source-repo files aligned there too
+- in consumer apps, use `./node_modules/prisma-php/dist/docs` as the installed docs location; do not assume a root-level `./dist/docs` directory exists
+- when updating Prisma PHP package/docs sources in the Prisma PHP package source repo, keep the source-repo `AGENTS.md` and source-repo `dist/docs` aligned; if that repo also maintains `.github/copilot-instructions.md` or `.github/instructions/**/*.instructions.md`, keep those source-repo files aligned there too
 
 ## Runtime lookup for AI
 
@@ -44,10 +45,12 @@ Use this map only after `prisma-php.json`, matching workspace instructions, inst
 | Need to verify | Runtime/source file |
 | --- | --- |
 | route root scoping, HTML fragment parsing, component tag compilation, prop casing | `vendor/tsnc/prisma-php/src/PHPX/TemplateCompiler.php` |
+| PHPX class composition, `getMergeClasses(...)`, and frontend `twMerge(...)` expression generation | `vendor/tsnc/prisma-php/src/PHPX/PHPX.php`, `vendor/tsnc/prisma-php/src/PHPX/TwMerge.php` |
 | imported PHP partial execution, one-root enforcement, prop serialization, imported `#[Exposed]` functions | `vendor/tsnc/prisma-php/src/ImportComponent.php` |
 | metadata, custom head tags, dynamic head/footer scripts | `vendor/tsnc/prisma-php/src/MainLayout.php` |
 | route and component maps | `vendor/tsnc/prisma-php/src/PrismaPHPSettings.php`, `settings/files-list.json`, `settings/component-map.json` |
-| request data, dynamic params, redirects, function-call requests | `vendor/tsnc/prisma-php/src/Request.php` |
+| request data, dynamic params, redirects, RPC/navigation wire detection (`$isRpc`, `$isNavigation`, `$isWire`) | `vendor/tsnc/prisma-php/src/Request.php` |
+| CSRF cookie family (`pp_csrf`, `pp_csrf_<port>`), token issuing and validation | `vendor/tsnc/prisma-php/src/Security/Csrf.php` |
 | exposed functions | `vendor/tsnc/prisma-php/src/Attributes/Exposed.php`, `vendor/tsnc/prisma-php/src/Attributes/ExposedRegistry.php` |
 | validation | `vendor/tsnc/prisma-php/src/Validator.php`, `vendor/tsnc/prisma-php/src/Rule.php` |
 | env values | `vendor/tsnc/prisma-php/src/Env.php` |
@@ -116,10 +119,13 @@ Use the docs router to learn how Prisma PHP implements a task. Use `./prisma-php
 - **Creating, editing, composing, or reviewing PHPX components, props, children, fragments, icons, buttons, accordions, or component file placement**  
   Read `components.md`
 
+- **Tailwind utility class composition, `getMergeClasses(...)`, `PP\PHPX\TwMerge`, or frontend `twMerge(...)` usage**  
+  Confirm `tailwindcss` in `prisma-php.json`, then read `components.md` for PHPX emission, `typescript.md` for app-level helper registration, and `layouts-and-pages.md` for route examples
+
 - **TypeScript frontend tooling, the `typescript` feature flag, the root `ts/` directory, `ts/main.ts`, npm packages, or registered browser helpers used from template expressions and PulsePoint scripts**  
   Read `typescript.md`, then use `pulsepoint.md`, `layouts-and-pages.md`, or `components.md` for the affected component boundary
 
-- **Loading data, calling backend logic from the frontend, `pp.fetchFunction(...)`, `#[Exposed]`, route-local mutations, streaming responses, or interactive backend validation**  
+- **Loading data, calling backend logic from the frontend, `pp.rpc(...)`, `#[Exposed]`, route-local mutations, streaming responses, or interactive backend validation**  
   Read `fetching-data.md`
 
 - **AI integration, provider SDKs, chat UIs, streamed assistant output, or deciding between page-local assistant UI, websocket, and MCP tools**  
@@ -134,7 +140,7 @@ Use the docs router to learn how Prisma PHP implements a task. Use `./prisma-php
 - **Environment variables, `.env`, `PP\Env`, `Env::get`, `Env::string`, `Env::bool`, `Env::int`, feature flags, host and port config, or runtime bootstrap settings**  
   Read `env.md`, then verify the official env docs at `env` and `env-file`
 
-- **Bootstrap flow, request initialization, `FUNCTION_CALL_SECRET`, `prisma_php_csrf`, route resolution, or runtime init order**  
+- **Bootstrap flow, request initialization, `FUNCTION_CALL_SECRET`, `pp_csrf`, route resolution, or runtime init order**  
   Read `bootstrap-runtime.md`, then use `env.md`, `fetching-data.md`, or `error-handling.md` as needed
 
 - **File uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename flows, replace flows, delete flows, allowed file types, upload size rules, or file manager UI behavior**  
@@ -143,7 +149,7 @@ Use the docs router to learn how Prisma PHP implements a task. Use `./prisma-php
 - **SMTP setup, `.env` mail variables, `PP\PHPMailer\Mailer`, HTML bodies, plain-text bodies, recipients, reply-to, CC, BCC, or attachments**  
   Read `email.md`, then verify the official email docs at `email-get-started`
 
-- **Ratchet websocket setup, `IoServer`, `HttpServer`, `WsServer`, `ConnectionManager`, browser `WebSocket`, or realtime route behavior**  
+- **Named sockets, `pp.socket(...)`, `SocketRegistry`, `Socket`, `SocketPool`, the Ratchet socket server, or realtime route behavior**  
   Read `websocket.md`, then verify the official websocket docs in this order: `websocket-get-started`, `websocket-chat-app`
 
 - **MCP support, `#[McpTool]`, `#[Schema]`, `PhpMcp\Server\Server`, `StreamableHttpServerTransport`, AI tool endpoints, or `src/Lib/MCP/mcp-server.php`**  
@@ -167,9 +173,12 @@ Use the docs router to learn how Prisma PHP implements a task. Use `./prisma-php
 - **API-style routes, JSON responses, handlers, webhooks, form-processing endpoints, `route.php`, or request validation in handlers**  
   Read `route-handlers.md`
 
-- **Swagger or OpenAPI generation, `swaggerDocs`, `pphp-swagger.json`, `create-swagger-docs`, or `settings/prisma-schema-config.json`**  
+- **Swagger or OpenAPI generation, `swaggerDocs`, generated per-model swagger docs, `create-swagger-docs`, or `settings/prisma-schema-config.json`**  
   Read `swagger-docs.md`
 
+- **Writing or running app tests, PHPUnit, the root `tests/` directory, `npm run test`, or verifying a change with the test suite**  
+  Read `testing.md`, then the project's `tests/README.md`
+
 - **Upgrading Prisma PHP, enabling features, syncing framework-managed project files, or running project updates**  
   Read `upgrading.md`
 
@@ -202,6 +211,7 @@ The current Prisma PHP docs shipped here include:
 - `pulsepoint.md`
 - `route-handlers.md`
 - `swagger-docs.md`
+- `testing.md`
 - `typescript.md`
 - `upgrading.md`
 - `validator.md`
@@ -211,7 +221,7 @@ This inventory exists to help AI find the right Prisma PHP guidance quickly. It
 
 When a task depends on optional capabilities such as `backendOnly`, `swaggerDocs`, `typescript`, `websocket`, or `mcp`, inspect `./prisma-php.json` before assuming the generated scaffold exists.
 
-When adding or reviewing AI guidance, do not stop at older docs only. Make sure the guidance also covers `backend-only.md`, `email.md`, `env.md`, `get-started-ia.md`, `mcp.md`, `swagger-docs.md`, `typescript.md`, and `websocket.md`, plus newer behavior documented in `fetching-data.md` and `metadata-and-og-images.md`.
+When adding or reviewing AI guidance, do not stop at older docs only. Make sure the guidance also covers `backend-only.md`, `email.md`, `env.md`, `get-started-ia.md`, `mcp.md`, `swagger-docs.md`, `typescript.md`, and `websocket.md`, plus newer behavior documented in `fetching-data.md`, `metadata-and-og-images.md`, and `testing.md`.
 
 ## Framework-generated files
 
@@ -232,8 +242,10 @@ When organizing a growing Prisma PHP app, keep route code and reusable code sepa
 - keep `src/app` focused on the route tree, route-local layouts, pages, handlers, and route-scoped partials
 - prefer `src/Components` for reusable application UI components shared across multiple routes or layouts
 - keep reusable non-UI code such as services, auth, middleware, Prisma classes, and helper libraries in `src/Lib`
+- treat route-private folders such as `src/app/<route>/_components` as an implementation detail for files that stay owned by that route only
 - treat generated libraries such as `src/Lib/PHPXUI` and `src/Lib/PPIcons` as library-specific surfaces governed by their manifests and matching `.github/instructions/**/*.instructions.md` files
 - if a partial starts in `src/app` but becomes shared across the app, promote it into `src/Components`
+- do **not** default to creating `src/app/<route>/_components` for app-owned section components such as `HeroSection`, `FormSection`, or `SidebarSection`; prefer `src/Components` unless the user explicitly wants route-local colocation and the files are truly private to that route
 - do **not** default to placing app-wide reusable components under `src/app` unless the user explicitly wants route-local colocation
 
 ## HTML-first component tag contract
@@ -306,15 +318,18 @@ When a task involves Prisma PHP CLI usage, keep the command guidance aligned wit
 
 For normal full-stack Prisma PHP work, assume the user wants the PulsePoint-first approach unless they explicitly ask otherwise.
 
-PulsePoint is the primary JavaScript authoring model for frontend work in Prisma PHP. For normal page behavior, keep the client logic inside a plain inline `<script>` within the route or imported-partial root, let Prisma PHP scope and execute it, and prefer `pp.fetchFunction(...)` over ad hoc endpoints.
+PulsePoint is the primary JavaScript authoring model for frontend work in Prisma PHP. For normal page behavior, keep the client logic inside a plain inline `<script>` within the route or imported-partial root, let Prisma PHP scope and execute it, and prefer `pp.rpc(...)` over ad hoc endpoints.
 
 Default interaction stack:
 
 1. render route UI with `index.php`
 2. keep browser-side interactivity in PulsePoint
-3. call backend PHP from the frontend with `pp.fetchFunction(...)`
+3. call backend PHP from the frontend with `pp.rpc(...)`
 4. mark callable PHP functions or methods with `#[Exposed]`
 5. validate and normalize input on the PHP side with `PP\Validator`
+6. use `pp.socket(...)` (named sockets) only when the flow is genuinely long-lived and bidirectional — chat, presence, live feeds
+
+`pp.rpc(...)` is the runtime RPC API. Framework-level RPC failures (unknown function, auth, roles, CSRF, origin, rate limit, server error) arrive as HTTP error statuses with an `{"error": "..."}` body and **reject** the `pp.rpc(...)` promise, so wrap calls in `try/catch` when the UI reacts to failures. Routine, expected validation feedback should still be returned as structured data (`success`, `errors`, normalized values), not thrown.
 
 Treat this as the default for:
 
@@ -336,7 +351,7 @@ Do **not** default to:
 - a PHP-only interaction style
 - plain browser-DOM wiring when PulsePoint state, bindings, and native `on*` handlers already fit the task
 - ad hoc `fetch('/api/...')` patterns
-- extra `route.php` files for page-local interactions that already fit `pp.fetchFunction(...)`
+- extra `route.php` files for page-local interactions that already fit `pp.rpc(...)`
 - a separate Node realtime or tool server when the documented Prisma PHP runtime already fits the task
 
 Choose a more PHP-only or handler-only pattern only when:
@@ -364,7 +379,7 @@ Also follow these route-file rules:
 - `index.php` and nested `layout.php` must render a single parent HTML element
 - use that single parent element as the route boundary; if the visible content should stay inside a semantic element such as `<main>`, `<section>`, or `<article>`, wrap it in a neutral parent such as `<div>`
 - for normal pages and nested layouts, do **not** manually author `pp-component` on that root; Prisma PHP adds it automatically
-- author a plain `<script>` tag inside that root when PulsePoint logic is needed and do **not** add `type="text/pp"` manually
+- author a plain `<script>` tag inside that root when PulsePoint logic is needed and do **not** put any `type` attribute on it — the runtime only recognizes untyped component scripts
 - keep the `<script>` as the last child of the route boundary, usually as a sibling of the visible content container instead of nesting it inside the semantic content element by default
 - do **not** leave the `<script>` outside the route boundary
 - write PulsePoint state, derived values, and functions directly at the top level of that script; do **not** wrap them in `DOMContentLoaded`, an IIFE, manual `pp.mount()` calls, or custom scoping helpers
@@ -424,7 +439,7 @@ Do not:
 
 - put a sibling `<script>` next to a route root or imported partial root
 - manually add `pp-component` inside imported partial source
-- manually add `type="text/pp"` to route or imported-partial scripts
+- add any `type` attribute to route or imported-partial component scripts
 - wrap imported-partial PulsePoint code in `DOMContentLoaded`, an IIFE, manual `pp.mount()` calls, or custom auto-execute helpers
 
 ## Metadata rules
@@ -440,19 +455,19 @@ Important metadata rules:
 
 ## Streaming and SSE rules
 
-Prisma PHP supports streaming through `pp.fetchFunction(...)` when an exposed function yields values.
+Prisma PHP supports streaming through `pp.rpc(...)` when an exposed function yields values.
 
 Default streaming rules:
 
 - prefer an exposed generator that simply yields strings or arrays
-- let Prisma PHP handle the SSE response automatically for normal `pp.fetchFunction(...)` streaming
+- let Prisma PHP handle the SSE response automatically for normal `pp.rpc(...)` streaming
 - on the client, put stream UI updates in `onStream`, `onStreamError`, and `onStreamComplete`
 - do not wait for a final JSON payload when the response is streamed
 
 Current parsing rules AI should know:
 
 - Prisma PHP sends streamed payloads as SSE `data:` lines
-- the built-in `pp.fetchFunction(...)` stream parser currently forwards only `data:` lines to `onStream`
+- the built-in `pp.rpc(...)` stream parser currently forwards only `data:` lines to `onStream`
 - `event:`, `id:`, and `retry:` may be emitted by low-level SSE helpers, but the built-in stream callback currently ignores them
 - prefer JSON values or single-line strings for streamed chunks instead of multi-line text blobs
 
@@ -481,7 +496,7 @@ Important: creating a route means creating or updating the correct folder and ro
 - use `error.php` for route or app-level error UI
 - use `loading.php` when the task is specifically about a loading UI state for a route subtree
 
-For normal route-local interactivity, prefer `index.php` plus PulsePoint and `pp.fetchFunction(...)` over inventing extra handlers.
+For normal route-local interactivity, prefer `index.php` plus PulsePoint and `pp.rpc(...)` over inventing extra handlers.
 
 In a consumer app, also verify `backendOnly` in `prisma-php.json`:
 
@@ -516,6 +531,7 @@ Use this auth decision flow:
 
 Important auth rules:
 
+- the auth classes are app-owned files under `src/Lib/Auth` in the `Lib\Auth` namespace — write `use Lib\Auth\Auth;` and `use Lib\Auth\AuthConfig;`, never `PP\Auth\...`
 - route privacy strategy is configured from `AuthConfig.php`
 - Prisma PHP supports both public-default and private-default route protection strategies
 - Prisma PHP defaults to public routes, so keep the public-default strategy when the app will expose many public pages
@@ -610,26 +626,34 @@ Important env rules:
 
 ## WebSocket rules
 
-When the task involves realtime messaging, presence, live dashboards, `Ratchet`, or browser `WebSocket`, read `websocket.md` first.
+When the task involves realtime messaging, presence, live dashboards, chat, `pp.socket(...)`, or `Ratchet`, read `websocket.md` first.
 
-Prisma PHP websocket support follows a Ratchet-based PHP server plus a `ConnectionManager` under `src/Lib/Websocket`. Do not replace that default with Socket.IO, a separate Node server, or an unrelated hosted realtime service unless the user explicitly asks for a different architecture.
+Prisma PHP realtime support is built on **named sockets**: `pp.socket(name, args, handlers)` in the browser, and a Ratchet-based server under `src/Lib/Websocket` that dispatches each connection to a handler registered with `SocketRegistry`. Do not replace that default with Socket.IO, a separate Node server, raw `new WebSocket(...)` wiring, or an unrelated hosted realtime service unless the user explicitly asks for a different architecture.
 
 Use this websocket workflow:
 
 1. read `websocket.md`
 2. inspect whether websocket support is enabled in `prisma-php.json` in the target app
-3. inspect `src/Lib/Websocket`
-4. inspect the route or client script that opens the browser `WebSocket`
+3. inspect `src/Lib/Websocket`, especially `sockets.php` for the registered socket names
+4. inspect the route script that calls `pp.socket(...)`
 5. inspect `settings/restart-websocket.ts` when local restart behavior matters
 6. inspect framework internals only when the docs do not answer the task
 
 Important websocket rules:
 
+- connect from the browser with `pp.socket(name, args, handlers)`; do **not** generate raw `new WebSocket(...)` wiring for app realtime work
+- register server handlers with `SocketRegistry::register(...)` in `src/Lib/Websocket/sockets.php`; socket names are unique application-wide
+- do not put socket handlers in route files — route files are not loaded by the socket server process
+- keep the wire contract intact: one endpoint (`/__pulsepoint/ws`), the function named in the `name` query parameter, arguments as the connection's first JSON frame, one JSON value per frame in either direction, and `{"error": "..."}` (that key alone) reserved for failures
 - use `src/Lib/Websocket/websocket-server.php` as the source of truth for startup behavior
-- use `src/Lib/Websocket/ConnectionManager.php` as the lifecycle boundary for clients and broadcasts
-- preserve documented env vars and defaults: `WS_NAME`, `WS_VERSION`, `WS_HOST`, `WS_PORT`, `WS_VERBOSE`, `APP_TIMEZONE`
+- use `src/Lib/Websocket/ConnectionManager.php` as the wire and lifecycle boundary (handshake security, argument frame, dispatch, limits)
+- use `SocketPool` for broadcasts; keep authenticated and guest traffic in separate pools
+- declare auth with `requireAuth` / `allowedRoles` at registration; the handshake is verified against the JWT auth cookie before the handler runs
+- a `Socket::send(...)` that returns `false` means the browser is gone — stop sending, it is not an error
+- preserve documented env vars and defaults: `WS_NAME`, `WS_VERSION`, `WS_HOST`, `WS_PORT`, `WS_VERBOSE`, `APP_TIMEZONE`, `MAX_WEBSOCKET_CONNECTIONS`, `MAX_WEBSOCKET_MESSAGE_BYTES`, `MAX_WEBSOCKET_MESSAGES_PER_WINDOW`, `WEBSOCKET_RATE_WINDOW_SECONDS`, `WEBSOCKET_IDLE_TIMEOUT_SECONDS`, `WEBSOCKET_ALLOWED_ORIGINS`
 - preserve CLI overrides through `--host=...`, `--port=...`, and `--verbose=...`
 - preserve the documented casing `src/Lib/Websocket`
+- in development, `settings/bs-config.ts` proxies `/__pulsepoint/ws` from the BrowserSync origin to the Ratchet server, so `pp.socket(...)` needs no `url` option; pass `url` only outside that proxy
 - for existing apps, enable `websocket` in `prisma-php.json` and run `npx pp update project -y` before inventing manual scaffolding
 
 ## MCP rules
@@ -681,12 +705,15 @@ Important ORM rules:
 
 ## Validation rules
 
-When a task involves user input, form handling, search params, JSON payloads, `pp.fetchFunction(...)`, `route.php` bodies, or tool parameters, do not trust raw values.
+When a task involves user input, form handling, search params, JSON payloads, `pp.rpc(...)`, `route.php` bodies, or tool parameters, do not trust raw values.
 
 Default Prisma PHP validation rules:
 
 - use `PP\Validator` as the backend validation and normalization layer
 - prefer the `Rule` builder for rule-based validation
+- start `Rule` builders with `Rule::required()`, `Rule::optional()`, or `Rule::make()`
+- chain rule methods such as `->min(...)`, `->max(...)`, `->email()`, and `->regex(...)` on that builder instance
+- do **not** generate static calls such as `Rule::max(80)`; for optional constrained fields use `Rule::optional()->max(80)` or `Rule::make()->max(80)`
 - validate in PHP even when the frontend already performs local checks
 - return structured validation results for expected failures
 - do not treat routine invalid input as an uncaught exception
@@ -696,6 +723,7 @@ When internals matter, the documented Prisma PHP core validator location is:
 
 ```txt
 vendor/tsnc/prisma-php/src/Validator.php
+vendor/tsnc/prisma-php/src/Rule.php
 ```
 
 ## PulsePoint rules
@@ -706,13 +734,15 @@ Also follow these rules:
 
 - treat PulsePoint as the primary JavaScript authoring model for normal full-stack frontend work
 - keep page and imported-partial client logic inside the boundary's plain `<script>` tag instead of building extra DOM-ready or self-executing wrappers
-- prefer `pp.fetchFunction(...)` over ad hoc `fetch('/api/...')` calls for page-local PHP interactions
+- prefer `pp.rpc(...)` over ad hoc `fetch('/api/...')` calls for page-local PHP interactions
 - reserve plain browser JavaScript outside PulsePoint for external libraries, low-level browser APIs, and reusable helpers in `ts/`
 - do not invent undocumented PulsePoint helpers or directives
 - do not write React, Vue, Alpine, or Livewire syntax and call it PulsePoint
 - keep backend concerns separate from PulsePoint runtime concerns
 - prefer simple documented runtime primitives over abstractions copied from other ecosystems
-- use `pp-style` for template-driven inline CSS and plain `style` for fully static inline CSS
+- do not treat app-registered helpers such as `twMerge(...)` as PulsePoint built-ins; route those tasks through the Tailwind-enabled Prisma PHP docs after checking feature flags
+- use `pp-style` whenever inline CSS contains `{...}` interpolation or any other template-driven/reactive value, and reserve plain `style` for fully static inline CSS
+- do **not** generate reactive inline CSS inside a plain `style` attribute such as `style="width: {progress}%";` use `pp-style="width: {progress}%";` instead so source markup stays editor-friendly
 - use `pp-spread="{...attrs}"` for dynamic attribute objects and omit nullish values from those objects
 - use `pp-for` only on `<template>` with `item in items` or `(item, index) in items`
 - use plain `key` for keyed diffing; do not invent `pp-key`
@@ -730,6 +760,8 @@ Also follow these rules:
 - use kebab-case component attributes and rely on the runtime to hydrate camelCase PHPX properties and PulsePoint props
 - keep component file names and class names aligned
 - preserve documented PHPX patterns for `$props`, `$children`, `$class`, and `getAttributes(...)`
+- in Tailwind-enabled apps, use `getMergeClasses(...)` and `PP\PHPX\TwMerge::merge(...)` as emitters of frontend `twMerge(...)` expressions instead of finalizing Tailwind class conflicts in PHP
+- when a route or imported partial needs direct Tailwind-aware class composition, treat `twMerge(...)` as an app-level browser helper available only when `tailwindcss` is enabled
 - follow documented component placement and grouping conventions before inspecting framework internals
 
 ## When to inspect framework internals
@@ -740,6 +772,8 @@ Useful app-mode core locations include:
 
 ```txt
 vendor/tsnc/prisma-php/src
+vendor/tsnc/prisma-php/src/PHPX/PHPX.php
+vendor/tsnc/prisma-php/src/PHPX/TwMerge.php
 vendor/tsnc/prisma-php/src/PHPX/TemplateCompiler.php
 vendor/tsnc/prisma-php/src/ImportComponent.php
 vendor/tsnc/prisma-php/src/MainLayout.php