npm - prisma-php - Versions diffs - 0.0.2 → 0.0.4 - Mend

prisma-php 0.0.2 → 0.0.4

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 (14) hide show

package/.github/copilot-instructions.md +24 -0
package/dist/docs/authentication.md +1 -0
package/dist/docs/components.md +38 -3
package/dist/docs/error-handling.md +3 -0
package/dist/docs/fetching-data.md +38 -4
package/dist/docs/file-manager.md +4 -2
package/dist/docs/index.md +20 -4
package/dist/docs/layouts-and-pages.md +59 -4
package/dist/docs/prisma-php-orm.md +1 -0
package/dist/docs/project-structure.md +11 -2
package/dist/docs/pulsepoint.md +139 -361
package/dist/docs/route-handlers.md +2 -0
package/dist/docs/validator.md +293 -0
package/package.json +1 -1

package/.github/copilot-instructions.md ADDED Viewed

@@ -0,0 +1,24 @@
+# Project Guidelines
+## Source Of Truth
+- Treat `dist/docs/index.md` as the entry point for Prisma PHP guidance in this repo.
+- Read the matching doc in `dist/docs` before generating or editing framework-specific Prisma PHP code.
+## Route File Conventions
+- For PulsePoint-aware `index.php` and `layout.php`, keep file order as PHP, then HTML, then one `<script>` block.
+- `index.php` and nested `layout.php` must render a single parent HTML element. Treat that root like a React-style component boundary rather than loose sibling markup.
+- Only the root `layout.php` should define `<html>`, `<head>`, and `<body>`. When PulsePoint is present, keep `MainLayout::$children;` inside one clear wrapper.
+## Component Boundary Rules
+- Distinguish PHPX class components from `ImportComponent` partials.
+- `ImportComponent` partials must output exactly one root element because Prisma PHP attaches serialized props and a stable `pp-component` attribute to that root.
+- Do not manually add `pp-component` unless a documented framework feature injects it for that boundary.
+## Relevant Docs
+- Route and layout structure: `dist/docs/layouts-and-pages.md`
+- PulsePoint runtime rules: `dist/docs/pulsepoint.md`
+- Component and `ImportComponent` rules: `dist/docs/components.md`

package/dist/docs/authentication.md CHANGED Viewed

@@ -193,6 +193,7 @@ The documented login flow uses:
 When generating credentials auth, do not trust raw request data.
 For backend validation and normalization, default to Prisma PHP’s validation layer rather than browser-only checks. In this docs set, that means using the documented validation guidance alongside `PP\Validator`-style server validation patterns from the rest of the local docs.
+Read `validator.md` before generating credential validation, registration validation, or auth-related request normalization.
 ## Social authentication

package/dist/docs/components.md CHANGED Viewed

@@ -69,6 +69,8 @@ This is the right mental model for:
 - componentized partials that PulsePoint should hydrate later
 - keeping PHP templating ergonomics while still producing component-aware markup
+For `ImportComponent`, think in terms of a React-style single-root component: one parent element defines the island boundary, Prisma PHP serializes props onto that root, and the framework injects a stable `pp-component` attribute there. Do not design imported partials as loose sibling markup.
 AI must not collapse these two models into one.
 - **PHPX** is for class-based component authoring.
@@ -87,6 +89,8 @@ AI must not collapse these two models into one.
 - when a component needs reactivity, distinguish between static PHP props and reactive PulsePoint props
 - when a component requires grouped sub-components, follow the documented same-file naming pattern like `Accordion`, `AccordionItem`, `AccordionTrigger`, and `AccordionContent`
 - when using `ImportComponent`, always ensure the imported file renders **exactly one root element**
+- treat the `ImportComponent` root as the real component boundary because Prisma PHP serializes props onto it and injects `pp-component`
+- do not manually add `pp-component` inside imported partial source; let Prisma PHP inject it
 ## Component file placement and naming
@@ -253,6 +257,8 @@ Prisma PHP:
 - use `ImportComponent` for PHP partials, not for PHPX class components
 - require exactly one root element in the imported file
+- keep the imported partial in Prisma PHP order: PHP preamble first, then one parent HTML element; if client script is needed, place the `<script>` inside that parent so the rendered output still has one root
+- treat that single root as the component boundary that receives `pp-component` and serialized props
 - treat the imported output as a PulsePoint-ready island boundary
 - pass server data as props and let Prisma PHP serialize them into attributes
 - use mustache-valued props when passing reactive PulsePoint bindings into imported partials
@@ -309,20 +315,49 @@ use PP\ImportComponent;
 The imported PHP file must output **exactly one root element**.
+That root is not just for layout or styling. It is the element Prisma PHP augments with `pp-component` and serialized props.
+A leading PHP block for imports, variables, helpers, or `#[Exposed]` functions is valid. Root counting applies to the emitted top-level HTML/XML nodes only.
+For imported Prisma PHP partials, keep the file in this shape:
+1. PHP
+2. one parent HTML element
+3. optional `<script>` inside that parent element
+If the file emits a second top-level tag, including a sibling `<script>`, Prisma PHP will fail with an error such as `ImportComponent requires EXACTLY one root element. Found 2 root element(s)`.
 Correct:
 ```php
+<?php
+$title = 'Search';
+?>
 <div class="rounded-lg border bg-card p-4">
-    <h2 class="font-medium">Search</h2>
+    <h2 class="font-medium"><?= $title ?></h2>
     <input value="{query}" oninput="{(e) => setQuery(e.target.value)}" />
+    <script type="text/pp">
+        console.log('Search component ready');
+    </script>
 </div>
 ```
 Incorrect:
 ```php
-<h2 class="font-medium">Search</h2>
-<input value="{query}" oninput="{(e) => setQuery(e.target.value)}" />
+<?php
+$title = 'Search';
+?>
+<section class="rounded-lg border bg-card p-4">
+    <h2 class="font-medium"><?= $title ?></h2>
+</section>
+<script type="text/pp">
+    console.log('This script is a second root element');
+</script>
 ```
 ## `ImportComponent` prop serialization rules

package/dist/docs/error-handling.md CHANGED Viewed

@@ -6,6 +6,7 @@ related:
   description: Learn more about the features mentioned on this page by reading the Prisma PHP docs.
   links:
     - /docs/error-handler
+    - /docs/php-validator
     - /docs/route-php
     - /docs/index-php
     - /docs/pages-and-layouts
@@ -62,6 +63,8 @@ In Prisma PHP, the recommended pattern is generally:
 - return a structured response or message
 - avoid letting routine validation failures become fatal exceptions
+Read `validator.md` for the detailed local guidance on helper selection, rule syntax, and `Validator::withRules(...)` behavior.
 ### Form or direct function example
 ```php filename="src/app/contact/index.php"

package/dist/docs/fetching-data.md CHANGED Viewed

@@ -6,6 +6,7 @@ related:
   description: Learn more about the features mentioned in this page by reading the Prisma PHP docs.
   links:
     - /docs/fetch-function
+    - /docs/php-validator
     - /docs/index-php
     - /docs/route-php
     - /docs/pages-and-layouts
@@ -18,6 +19,38 @@ Prisma PHP has a different mental model from Next.js. Instead of focusing on Rea
 When using `pp.fetchFunction(...)`, the PHP function must be explicitly exposed with `#[Exposed]`. Functions are private by default, so a non-exposed function cannot be called from the client.
 For validation, the default backend pattern should be **`PP\Validator`**. Use it to sanitize, cast, and validate values inside exposed functions and route handlers. This keeps the browser reactive while keeping the authoritative validation on the server.
+Read `validator.md` alongside this page when you need the detailed helper list, rule syntax options, or the `Validator::withRules(...)` return contract.
+## Default AI decision rule
+For **normal interactive full-stack Prisma PHP work**, AI should default to this stack:
+1. render the route with `index.php`
+2. use **PulsePoint** for browser-side state and reactive UI behavior
+3. use **`pp.fetchFunction(...)`** for frontend-to-PHP calls
+4. mark callable PHP functions with **`#[Exposed]`**
+5. use **`PP\Validator`** for authoritative backend validation and normalization
+This should be the default for cases such as:
+- live search
+- filters
+- pagination controls
+- quick edit dialogs
+- inline validation
+- toggles and status changes
+- modal-based mutations
+- optimistic-feeling dashboard interactions
+- route-local CRUD actions that belong to the current page
+Do **not** default to a more PHP-only interaction style for those cases unless the **user explicitly asks for PHP-only behavior**.
+A more PHP-only pattern is reasonable when:
+- the user explicitly asks for plain PHP, classic form submission, or no PulsePoint
+- the route is intentionally non-reactive
+- the task is a standalone API, webhook, integration endpoint, or public JSON route
+- the behavior must exist independently of the current page
 ## Validation is a server concern
@@ -49,6 +82,7 @@ For reactive UI work, the best Prisma PHP pattern is usually:
 4. return a structured object for the UI to render
 The official Validator docs recommend the **`Rule` builder** for most rule-based validation because it is easier to discover, easier to refactor, and less error-prone than raw pipe strings.
+`validator.md` is the local source of truth for how this docs set expects AI to apply that guidance.
 ## Recommended pattern for reactive Prisma PHP UIs
@@ -59,9 +93,9 @@ For normal interactive UI work in Prisma PHP, the default approach should be:
 3. call PHP from the frontend with `pp.fetchFunction(...)`
 4. expose callable functions with `#[Exposed]`
-This is the preferred pattern for live search, inline validation, toggles, quick edits, filtering, lightweight mutations, and similar route-local interactions.
+This is the preferred pattern for live search, inline validation, toggles, quick edits, filtering, lightweight mutations, pagination, modal workflows, and similar route-local interactions.
-Do **not** default to building extra `route.php` endpoints for every interactive action when `pp.fetchFunction(...)` is the better fit. Reserve `route.php` for explicit API-style endpoints, webhooks, JSON handlers, or routes that must be called independently of the page.
+Do **not** default to building extra `route.php` endpoints for every interactive action when `pp.fetchFunction(...)` is the better fit. Also do **not** default to a PHP-only interaction model for normal reactive page behavior unless the user explicitly asks for that style. Reserve `route.php` for explicit API-style endpoints, webhooks, JSON handlers, or routes that must be called independently of the page.
 ## Fetching data in Prisma PHP
@@ -617,7 +651,7 @@ When fetching data from Prisma PHP:
 - every function called through `pp.fetchFunction(...)` must use `#[Exposed]`
 - return structured validation results instead of relying on thrown exceptions for routine failures
 - use `Exposed` options to enforce auth, roles, or rate limits
-- prefer `route.php` for dedicated public or integration-facing endpoints
+- prefer `route.php` for dedicated public or integration-facing endpoints, not as the default answer for normal page-local interactivity
 - keep sensitive database access on the server side
 Because Prisma PHP runs the data logic in PHP, database credentials and internal query logic stay on the server.
@@ -634,4 +668,4 @@ Because Prisma PHP runs the data logic in PHP, database credentials and internal
 - `abortPrevious: true` helps cancel stale requests.
 - file uploads can be handled automatically without manual `FormData` in many cases.
 - `Exposed` can be used to declare authentication, allowed roles, and rate limits for callable functions.
-- for full-stack routes, load page data in `index.php` and use direct function invocation for interactive updates.
+- for full-stack routes, load page data in `index.php` and use PulsePoint plus direct function invocation for interactive updates unless the user explicitly asks for a PHP-only flow.

package/dist/docs/file-manager.md CHANGED Viewed

@@ -15,6 +15,7 @@ related:
 Prisma PHP file handling should follow the documented **File Manager** model and standard PHP upload rules, not assumptions copied from Laravel storage disks, Symfony upload abstractions, Livewire temporary uploads, or custom Node-style multipart pipelines.
 If a task involves file uploads, upload forms, `$_FILES`, upload size limits, allowed file types, renaming, deleting, replacing files, or building a file manager UI, AI agents should read the relevant Prisma PHP File Manager docs first and keep the implementation aligned with the installed Prisma PHP version.
+When the task also involves validating rename fields, labels, descriptions, or other non-file inputs, read `validator.md` alongside this page.
 ## AI rule: read the File Manager docs first
@@ -32,7 +33,7 @@ Do not assume another framework's storage abstraction applies directly.
 ## Read this doc when you need
 - **basic upload form setup, `multipart/form-data`, or raw `$_FILES` behavior** → official `get-started-file`
-- **upload validation and normalization for names or request values** → official `php-validator` plus local validation guidance in `fetching-data.md`, `error-handling.md`, and `route-handlers.md`
+- **upload validation and normalization for names or request values** → `validator.md` first, then official `php-validator`, plus local validation guidance in `fetching-data.md`, `error-handling.md`, and `route-handlers.md`
 - **a rendered upload page or full-stack file manager screen** → `index.php` plus `layouts-and-pages.md`
 - **a standalone upload endpoint, webhook-like file receiver, or direct JSON upload handler** → `route.php` plus `route-handlers.md`
 - **local dev reload issues caused by uploaded files changing on disk** → inspect `./settings/bs-config.ts` and exclude the upload directory from BrowserSync tracking
@@ -210,6 +211,7 @@ For file manager pages and upload-related actions, keep these concerns separate:
 - use route pages or route handlers according to the documented `index.php` versus `route.php` split
 Do not use filename cleanup as a substitute for validating other request data.
+For the full local validation contract, read `validator.md`.
 ## Organization guidance
@@ -277,7 +279,7 @@ When the user asks for upload or file-manager functionality, AI should usually f
 4. choose the upload destination directory
 5. if local reload becomes noisy, exclude the upload directory in `./settings/bs-config.ts`
 6. use `UploadFile` for upload, rename, update, and delete operations when it fits the documented workflow
-7. use `PP\Validator` for rename fields or other non-file request values
+7. read `validator.md`, then use `PP\Validator` for rename fields or other non-file request values
 8. return structured messages for expected failures
 9. inspect Prisma PHP internals only if the docs and local project usage are not enough

package/dist/docs/index.md CHANGED Viewed

@@ -8,7 +8,7 @@ related:
     - /docs/get-started
 ---
-{/_ AI agent hint: Prisma PHP uses local installed docs as the source of truth for the active project version. Before generating framework-specific code, read `prisma-php.json` first, then read the relevant docs from `node_modules/prisma-php/dist/docs`. For authentication, read `authentication.md` first, then verify the official auth docs: `auth-get-started`, `credentials`, and `state-manager-auth`. For file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, or file manager screens, read `file-manager.md` first, then verify the official File Manager docs: `get-started-file`. For ORM work, read `prisma-php-orm.md` before choosing schema, migration, or generation commands. For PulsePoint runtime behavior specifically, read `pulsepoint.md` before generating reactive UI code. For backend validation, sanitization, `Validator`, `Rule`, `pp.fetchFunction(...)` validation flows, or request validation in `route.php`, read `fetching-data.md`, `error-handling.md`, and `route-handlers.md`, then consult the official Validator docs. `PP\Validator` is a Prisma PHP core class located in `vendor/tsnc/prisma-php/src/Validator.php`. Route creation is file-based from `src/app`; Prisma PHP auto-generates route listings such as `files-list.json`, so AI agents must not create, edit, or maintain that file manually. _/}
+{/_AI agent hint: Prisma PHP uses local installed docs as the source of truth for the active project version. Before generating framework-specific code, read `prisma-php.json` first, then read the relevant docs from `node_modules/prisma-php/dist/docs`. For authentication, read `authentication.md` first, then verify the official auth docs: `auth-get-started`, `credentials`, and `state-manager-auth`. For file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, or file manager screens, read `file-manager.md` first, then verify the official File Manager docs: `get-started-file`. For ORM work, read `prisma-php-orm.md` before choosing schema, migration, or generation commands. For PulsePoint runtime behavior specifically, read `pulsepoint.md` before generating reactive UI code. For normal interactive full-stack page work, default to PulsePoint plus `pp.fetchFunction(...)` unless the user explicitly asks for a PHP-only interaction style. When building PulsePoint-aware `index.php` or `layout.php`, keep PHP first, HTML second, and one `<script>` block last, with the rendered route content inside a single parent HTML element that acts as the route-view boundary. For imported partial components, keep exactly one root element because Prisma PHP uses that root as the component boundary where serialized props and `pp-component` attach. For backend validation, sanitization, `Validator`, `Rule`, `pp.fetchFunction(...)` validation flows, or request validation in `route.php`, read `validator.md` first, then use `fetching-data.md`, `error-handling.md`, and `route-handlers.md` for context-specific patterns, then consult the official Validator docs. `PP\Validator` is a Prisma PHP core class located in `vendor/tsnc/prisma-php/src/Validator.php`. Route creation is file-based from `src/app`; Prisma PHP auto-generates route listings such as `files-list.json`, so AI agents must not create, edit, or maintain that file manually._/}
 Welcome to the Prisma PHP documentation!
@@ -33,13 +33,26 @@ Use this order:
 3. Inspect local project files.
 4. Inspect `vendor/tsnc/prisma-php/src` only when framework internals are necessary.
+### Default interactive pattern
+For typical full-stack Prisma PHP work, AI should assume this default:
+1. render route UI in `index.php`
+2. keep browser-side interactivity in **PulsePoint**
+3. call PHP from the frontend with **`pp.fetchFunction(...)`**
+4. expose callable functions with **`#[Exposed]`**
+5. validate and normalize incoming values in PHP with **`PP\Validator`**
+Do **not** default to PHP-only interaction flows for normal reactive UI work unless the user explicitly asks for that style.
 ### Read this doc when you need
 - **project setup or file placement** → `project-structure.md`
-- **pages, layouts, route creation, nested routes** → `layouts-and-pages.md`
+- **pages, layouts, route creation, nested routes, or PulsePoint-aware `index.php` and `layout.php` structure** → `layouts-and-pages.md`
 - **PHPX components, props, children, fragments, icons, buttons, accordions, or component composition** → `components.md`
 - **file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, file replacement, allowed file types, upload size rules, or file manager pages** → `file-manager.md`
 - **authentication strategy, `AuthConfig.php`, sign-in, sign-out, route privacy model, RBAC, credentials auth, social login, or auth state manager usage** → `authentication.md`
+- **validation, sanitization, casting, `PP\Validator`, `Rule`, or `Validator::withRules(...)`** → `validator.md`
 - **`pp.fetchFunction(...)`, `#[Exposed]`, page data loading, interactive validation with `Validator`** → `fetching-data.md`
 - **cache behavior and `CacheHandler`** → `caching.md`
 - **ORM, `schema.prisma`, database provider, migrations, generated PHP classes, `prisma.config.ts`, `.env` `DATABASE_URL`, or Prisma CLI workflow** → `prisma-php-orm.md`
@@ -57,7 +70,10 @@ Use this order:
 - do not guess routing, file conventions, request helpers, component APIs, reactive syntax, or auth behavior when local docs already define them
 - create routes by adding folders and route files under `src/app`
 - do not create, edit, or maintain `files-list.json`; Prisma PHP generates route listings automatically
-- when building interactive frontend behavior, prefer the documented PulsePoint pattern with browser-side reactive state and `pp.fetchFunction(...)` for server calls
+- when building interactive frontend behavior, prefer the documented PulsePoint pattern with browser-side reactive state and `pp.fetchFunction(...)` for server calls; treat this as the default unless the user explicitly asks for a PHP-only interaction pattern
+- when building PulsePoint inside `index.php` or `layout.php`, read `layouts-and-pages.md` together with `pulsepoint.md`, use PHP then HTML then one `<script>` block, keep route content inside a single parent HTML element, and treat that root as the route-view boundary
+- when importing a PHP partial with `ImportComponent`, require exactly one root element because Prisma PHP attaches serialized props and a stable `pp-component` attribute to that root; do not manually sprinkle `pp-component` across normal route markup
+- when building backend validation logic, read `validator.md` first, then use the route-specific docs for the request entry point
 - when using `pp.fetchFunction(...)`, expose the PHP function explicitly with `#[Exposed]`
 - when changing feature flags, update `prisma-php.json` first, then follow the documented update workflow
 - when building reusable PHPX components, read `components.md` first
@@ -78,7 +94,7 @@ Use `file-manager.md` as the local AI-awareness guide for:
 - choosing between a rendered upload page and a direct upload handler
 - validating non-file request values with `PP\Validator`
-After reading `file-manager.md`, verify the matching official docs at:
+After reading `file-manager.md`, read `validator.md` when non-file request values are involved, then verify the matching official docs at:
 1. `get-started-file`
 2. `php-validator` when auxiliary request validation is needed

package/dist/docs/layouts-and-pages.md CHANGED Viewed

@@ -1,9 +1,9 @@
 ---
 title: Layouts and Pages
-description: Learn how to create your first pages and layouts in Prisma PHP, and structure routes using the framework's file conventions.
+description: Learn how to create your first pages and layouts in Prisma PHP, structure routes with the framework's file conventions, and keep PulsePoint-aware route files predictable.
 related:
   title: API Reference
-  description: Learn more about the features mentioned in this page by reading the Prisma PHP routing documentation.
+  description: Learn more about the features mentioned in this page by reading the Prisma PHP routing and PulsePoint documentation.
   links:
     - /docs/pages-and-layouts
     - /docs/defining-routes
@@ -11,6 +11,7 @@ related:
     - /docs/private-folders
     - /docs/dynamic-route
     - /docs/index-php
+    - /docs/pulsepoint
     - /docs/route-php
 ---
@@ -28,7 +29,7 @@ When adding a page or nested route, create the correct folder and add the proper
 Prisma PHP has two important route entry files, and they serve different purposes.
-- `index.php` is the **UI entry point** for a route. Use it when the route should render HTML or a normal full-stack page.
+- `index.php` is the **UI entry point** for a route. Use it when the route should render HTML or a normal full-stack page. In full-stack projects, this is also the default home for route-local PulsePoint-driven interactivity.
 - `route.php` is the **direct handler entry point** for a route. Use it when the route should behave like an API endpoint, JSON endpoint, AJAX handler, form-processing endpoint, or other no-view server handler.
 A helpful project-level rule comes from `prisma-php.json`:
@@ -44,7 +45,57 @@ For the example project configuration below, `backendOnly` is `false`, so the de
 }
 ```
-If the user asks for a **route or page**, prefer `index.php`. If the user asks for an **API route**, direct handler, JSON endpoint, webhook, or AJAX route, prefer `route.php`.
+If the user asks for a **route or page**, prefer `index.php`. If the user asks for an **API route**, direct handler, JSON endpoint, webhook, or AJAX route, prefer `route.php`. Do not default to a PHP-only interaction style for normal page behavior when PulsePoint inside `index.php` is the better fit.
+## PulsePoint-aware file structure for `index.php` and `layout.php`
+For normal interactive full-stack routes, the default Prisma PHP mental model should be:
+1. page UI in `index.php`
+2. browser-side state in PulsePoint
+3. route-local server calls through `pp.fetchFunction(...)`
+4. backend validation through `PP\Validator`
+Only shift to a more PHP-only pattern when the user explicitly asks for it or when the route is intentionally non-reactive.
+When `index.php` or `layout.php` includes PulsePoint, keep the file in this order:
+1. PHP
+2. HTML
+3. SCRIPT
+In practice, that means:
+- put imports, server-side queries, request access, helper functions, and exposed PHP functions in the top PHP block
+- render the route markup after the PHP block
+- place one PulsePoint `<script>` block at the bottom of the file
+For the HTML portion, keep a **single parent HTML tag** around the route content, similar to React's single-root component rule. Treat that root as the page or layout boundary instead of as a throwaway wrapper.
+- In `index.php`, wrap the page UI in one parent element such as `<main>`, `<section>`, or `<article>`, and treat that root as the route view's component-style boundary.
+- In nested `layout.php`, wrap the shared layout UI and `<?= MainLayout::$children; ?>` in one parent element so the layout still behaves like one boundary.
+- If that markup is later extracted into an `ImportComponent` partial, preserve the same single-root structure so Prisma PHP can attach the stable `pp-component` attribute to that root element.
+- The root `layout.php` is the document shell and is the only layout that should contain `<html>` and `<body>`. Inside `<body>`, keep one clear wrapper around `<?= MainLayout::$children; ?>` when PulsePoint behavior is present.
+Example PulsePoint page structure:
+```php filename="src/app/dashboard/index.php"
+<?php
+$title = 'Dashboard';
+?>
+<section class="dashboard-page">
+        <h1><?= htmlspecialchars($title); ?></h1>
+        <p>Count: {count}</p>
+        <button onclick="setCount(count + 1)">Increment</button>
+</section>
+<script>
+    const [count, setCount] = pp.state(0);
+</script>
+```
+This order keeps server logic, rendered markup, and client reactivity easy to scan for both humans and AI tools.
 ## Creating a page
@@ -88,6 +139,7 @@ For example, to create a root layout:
 ```
 The root layout is defined at the top level of your app directory and wraps the content for the entire application.
+If this root layout uses PulsePoint, keep the same file order: PHP first, then the document HTML, then a single `<script>` block near the end of `<body>`.
 ## Creating a nested route
@@ -159,6 +211,7 @@ src/app/
 ```
 If you combine both layouts, the root layout wraps the blog layout, and the blog layout wraps both `src/app/blog/index.php` and `src/app/blog/[slug]/index.php`.
+Nested layouts should behave like single-root route views: one parent element should wrap the shared layout UI and `MainLayout::$children;`. Keep thinking in terms of one component-style boundary, not multiple sibling roots.
 ## Creating a dynamic segment
@@ -283,6 +336,8 @@ echo json_encode([
 - If a user asks for an API route or direct handler, prefer `route.php`.
 - The root layout is required and should contain the global HTML document structure.
 - Only the root layout should contain `<html>` and `<body>` tags.
+- When `index.php` or `layout.php` uses PulsePoint, structure the file as PHP, then HTML, then one `<script>` block.
+- `index.php` and nested `layout.php` should render one parent HTML element; only the root layout should contain `<html>` and `<body>`.
 - Layouts can be nested by placing `layout.php` files inside route folders.
 - Dynamic route parameters are available through `Request::$dynamicParams`.
 - Route groups let you organize routes and assign different layouts without affecting the URL.

package/dist/docs/prisma-php-orm.md CHANGED Viewed

@@ -39,6 +39,7 @@ vendor/tsnc/prisma-php/src/Validator.php
 ```
 `Validator` is the server-side validation layer for user input. It is not the ORM result layer.
+For the full local validation contract, helper overview, and rule patterns, read `validator.md`.
 Use this split:

package/dist/docs/project-structure.md CHANGED Viewed

@@ -59,13 +59,22 @@ If an AI agent is working on the project, it should inspect `prisma-php.json` be
 One of the most important capability flags is `backendOnly`.
-- When `backendOnly` is `false`, the project is a **full-stack Prisma PHP app**. In that mode, normal route UI should be implemented with `index.php`.
+- When `backendOnly` is `false`, the project is a **full-stack Prisma PHP app**. In that mode, normal route UI should be implemented with `index.php`, and interactive page behavior should usually be implemented with PulsePoint plus `pp.fetchFunction(...)`.
 - When `backendOnly` is `true`, the project is a **backend-only Prisma PHP app**. In that mode, route behavior will usually center on direct handlers such as `route.php`.
-- If a `route.php` file exists at a route segment, it acts as the direct handler entry point for that route and should be treated as the API-style or no-view path for that segment.
+- If a `route.php` file exists at a route segment, it acts as the direct handler entry point for that route and should be treated as the API-style or no-view path for that segment, not as the default destination for ordinary route-local interactivity.
 - In full-stack projects, if the user asks for a normal route or page, prefer `index.php`. If the user asks for an API route, JSON endpoint, form-processing endpoint, AJAX endpoint, or direct handler, prefer `route.php`.
 This helps AI and contributors choose the correct file without guessing based on other frameworks.
+For AI-assisted generation, the default full-stack route pattern should be:
+1. render page UI in `index.php`
+2. keep browser interactivity in PulsePoint
+3. use `pp.fetchFunction(...)` for frontend-to-PHP calls that belong to the page
+4. use `route.php` only when the behavior must exist as a standalone handler or API-style endpoint
+Only prefer a more PHP-only interaction pattern when the user explicitly asks for it.
 ### Framework-managed generated files
 Some files in a Prisma PHP project are framework-managed and should not be manually maintained as part of normal route work.