prisma-php 0.0.11 → 0.0.12

package/.github/copilot-instructions.md

@@ -2,9 +2,10 @@
 
 ## 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.
-- When updating AI guidance in this repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned.
+- For Prisma PHP applications, treat `node_modules/prisma-php/dist/docs/index.md` as the entry point for the installed framework version.
+- 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.
+- When updating Prisma PHP package/docs sources in this repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned so the published docs remain correct after install.
 - 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.
 
 ## Route File Conventions
@@ -17,26 +18,32 @@
 ## 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.
+- `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. For normal PulsePoint-aware route files, add `pp-component` to the single root element yourself.
 
 ## 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`
 - 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`

package/dist/docs/commands.md

@@ -7,6 +7,7 @@ related:
   links:
     - /docs/installation
     - /docs/upgrading
+    - /docs/typescript
 ---
 
 This guide explains what each Prisma PHP CLI command does, when to use it, and how the create and update workflows fit together.
@@ -163,6 +164,10 @@ npx create-prisma-php-app my-app --tailwindcss
 
 Enables TypeScript support for the frontend toolchain.
 
+When this flag is enabled, Prisma PHP should keep frontend TypeScript in the root `ts/` directory, register browser helpers from `ts/main.ts`, and use those registered globals from template expressions and PulsePoint component scripts.
+
+Read `typescript.md` for the TypeScript-specific workflow.
+
 ### Use this when
 
 - you want typed frontend code

package/dist/docs/get-started-ia.md

@@ -15,6 +15,8 @@ related:
 
 Prisma PHP is a good fit for AI features, but the right Prisma PHP pattern depends on what you are actually building.
 
+If a task involves provider-backed chat, prompt forms, streamed output, assistant panels, or deciding between page-local AI, websocket, and MCP, AI agents should read this page first and keep the implementation aligned with the installed Prisma PHP docs.
+
 For a normal user-facing chat box, assistant panel, prompt form, streamed summary, or similar page-local AI feature, the recommended Prisma PHP approach is:
 
 1. render the UI in `index.php`

package/dist/docs/index.md

@@ -10,7 +10,9 @@ related:
     - /docs/get-started-ia
 ---
 
-{/_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 environment variables, `.env`, `PP\Env`, `Env::get(...)`, `Env::string(...)`, `Env::bool(...)`, `Env::int(...)`, or runtime configuration, read `env.md` first, then verify the official env docs: `env` and `env-file`. 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 email sending, SMTP config, `.env` mail variables, `PP\PHPMailer\Mailer`, HTML or text bodies, recipients, reply-to, or attachments, read `email.md` first, then verify the official Email docs: `email-get-started`. For websocket support, Ratchet setup, `IoServer`, `HttpServer`, `WsServer`, `ConnectionManager`, connection lifecycle methods, browser `WebSocket`, or realtime UI flows, read `websocket.md` first, then verify the official websocket docs: `websocket-get-started` and `websocket-chat-app`. For MCP support, `#[McpTool]`, `#[Schema]`, `PhpMcp\Server\Server`, `StreamableHttpServerTransport`, or `src/Lib/MCP/mcp-server.php`, read `mcp.md` first, then verify the official MCP docs: `prisma-php-ai-mcp` and `ai-tools`. 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. For normal PulsePoint-aware route files such as `index.php` and nested `layout.php`, keep PHP first, then one parent HTML element that acts as the route-view boundary; when PulsePoint logic is present, put `pp-component` on that root and keep the `<script>` as the last child inside it. For imported partial components rendered with `ImportComponent::render(...)`, keep exactly one root element and place any component-local `<script>` inside that root; Prisma PHP injects `pp-component` on the imported root automatically. Do not confuse the route-file pattern with the imported-partial pattern. 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._/}
+Use this page as the routing entry point for the local Prisma PHP docs. If a task involves choosing which Prisma PHP guide to read before generating framework-specific code, start here and then jump to the matching page in `node_modules/prisma-php/dist/docs`.
+
+Before generating framework-specific code, read `prisma-php.json` first, then the matching local docs page. For auth read `authentication.md`; for env read `env.md`; for uploads read `file-manager.md`; for email read `email.md`; for websocket read `websocket.md`; for MCP read `mcp.md`; for ORM read `prisma-php-orm.md`; for reactive UI read `pulsepoint.md`; for validation read `validator.md`; for data loading read `fetching-data.md`; and for route or layout structure read `layouts-and-pages.md`.
 
 Welcome to the Prisma PHP documentation!
 
@@ -118,6 +120,7 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 - **backend-only Prisma PHP usage, API-first projects, `backendOnly`, CORS, separate frontend clients, or choosing `route.php` as the default route file** → `backend-only.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`
+- **frontend TypeScript tooling, the `typescript` flag, the `ts/` directory, `ts/main.ts`, npm packages, or registered browser helpers used from template expressions and PulsePoint scripts** → `typescript.md`
 - **environment variables, `.env`, `PP\Env`, `Env::get(...)`, `Env::string(...)`, `Env::bool(...)`, `Env::int(...)`, or runtime configuration** → `env.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`
 - **AI integration, provider SDKs, chat UIs, streamed assistant responses, or deciding between page-local AI features, websocket, and MCP** → `get-started-ia.md`
@@ -147,6 +150,7 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 - when the project is API-first or backend-only, read `backend-only.md`, inspect `backendOnly` in `prisma-php.json`, and default to `route.php` for normal route behavior
 - when reading runtime configuration, `.env`, or feature flags, read `env.md` first and prefer `PP\Env` typed helpers over repeated manual parsing
 - 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 the task involves frontend TypeScript tooling or registered browser helpers, read `typescript.md`, keep reusable module code in `ts/`, and call the registered globals from PulsePoint component scripts instead of placing `import` or `export` inside inline route scripts
 - when building PulsePoint inside `index.php` or `layout.php`, read `layouts-and-pages.md` together with `pulsepoint.md`, use one parent route root, put `pp-component` on that root, and keep the `<script>` inside it as the last child
 - when importing a PHP partial with `ImportComponent`, require exactly one root element and keep any partial-local `<script>` inside that root because Prisma PHP attaches serialized props and a stable `pp-component` attribute to that imported root
 - do not leave a PulsePoint `<script>` as a sibling outside the route root
@@ -175,6 +179,18 @@ For a normal chat UI, assistant panel, streamed summary, or other page-local AI
 
 Use `get-started-ia.md` as the local AI guide for provider-backed chat, streaming, and the boundary between page-local AI, websocket, and MCP tooling.
 
+## TypeScript
+
+Prisma PHP can use a Vite-backed TypeScript workflow when the `typescript` feature flag is enabled in `prisma-php.json`.
+
+Use `typescript.md` as the local AI guide for:
+
+- enabling TypeScript in new or existing projects
+- organizing frontend modules in `ts/`
+- registering browser helpers in `ts/main.ts`
+- installing npm packages for frontend utilities
+- using registered helpers from template expressions and PulsePoint scripts while keeping inline component scripts as plain JavaScript
+
 ## Env
 
 Prisma PHP includes a documented environment helper centered on `PP\Env`, which reads already-loaded runtime values and exposes typed accessors for strings, booleans, and integers.

package/dist/docs/installation.md

@@ -2,11 +2,11 @@
 title: Installation
 description: Learn how to create a new Prisma PHP application so AI agents can use the first-time setup flow instead of existing-project update commands.
 related:
-	title: Related docs
-	description: Read the full command reference and the existing-project update workflow.
-	links:
-		- /docs/commands
-		- /docs/upgrading
+  title: Related docs
+  description: Read the full command reference and the existing-project update workflow.
+  links:
+    - /docs/commands
+    - /docs/upgrading
 ---
 
 Create a new Prisma PHP app and run it locally.

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

@@ -15,6 +15,8 @@ Prisma PHP ORM gives Prisma PHP applications a schema-first, Prisma-style data l
 
 It uses your Prisma schema, Prisma migrations, and generated PHP classes so your application can query the database through the documented Prisma PHP API.
 
+If a task involves `schema.prisma`, migrations, generated Prisma PHP classes, `npx prisma ...`, or `npx ppo generate`, AI agents should read this page first and keep the workflow aligned with the installed Prisma PHP docs.
+
 ## ORM result shape rule
 
 Prisma PHP ORM query results should be treated as model-shaped objects returned by the generated Prisma PHP classes that follow `prisma/schema.prisma`.
@@ -75,7 +77,7 @@ Use this order:
 
 For Prisma PHP ORM tasks, AI should read:
 
-- `06-prisma-php-orm.md`
+- `prisma-php-orm.md`
 - the official Prisma PHP ORM docs for the installed version
 - `schema.prisma`
 - `prisma.config.ts`
@@ -196,24 +198,26 @@ Use this flow:
 6. when the user is using SQLite, prefer saving the database file inside the local `./prisma` directory
 7. for the normal local setup, use:
 
-```env
-DATABASE_URL="file:./prisma/dev.db"
-```
+  ```env
+  DATABASE_URL="file:./prisma/dev.db"
+  ```
 
-8. confirm the resolved path points to a valid project-local SQLite file such as `./prisma/dev.db`
-9. do not point the SQLite file at an unrelated root-level location when the project is using the standard Prisma PHP layout
-10. if the `./prisma` directory is the intended storage location, the SQLite database file should be created and saved there
-11. if the SQLite database file is missing, invalid, or not initialized yet, run:
+Then continue with these checks:
 
-```bash
-npx prisma migrate dev
-```
+- confirm the resolved path points to a valid project-local SQLite file such as `./prisma/dev.db`
+- do not point the SQLite file at an unrelated root-level location when the project is using the standard Prisma PHP layout
+- if the `./prisma` directory is the intended storage location, the SQLite database file should be created and saved there
+- if the SQLite database file is missing, invalid, or not initialized yet, run:
 
-12. after migration succeeds, run:
+  ```bash
+  npx prisma migrate dev
+  ```
 
-```bash
-npx ppo generate
-```
+- after migration succeeds, run:
+
+  ```bash
+  npx ppo generate
+  ```
 
 Important SQLite rule:
 

package/dist/docs/project-structure.md

@@ -1,20 +1,33 @@
 ---
 title: Project structure and organization
 nav_title: Project Structure
-description: Learn the folder and file conventions in Prisma PHP so AI agents can place features in the right files and folders.
+description: Learn the folder and file conventions in Prisma PHP, including the installed docs path and project-root AGENTS.md, so AI agents can place features in the right files and folders.
+related:
+    title: Related docs
+    description: Use the routing, handler, component, and TypeScript docs once you know where a change belongs.
+    links:
+        - /docs/pages-and-layouts
+        - /docs/route-php
+        - /docs/import-component
+        - /docs/typescript
+---
 
 This page provides an overview of the folder and file conventions in **Prisma PHP**, and recommendations for organizing your project. It follows the Prisma PHP routing model and mirrors the mental model of a Next.js App Router style project structure, adapted to how Prisma PHP actually works.
 
 If a task involves file placement, feature flags, route creation, or overall Prisma PHP app organization, AI agents should read this page first and use it as the directory-level source of truth before generating files.
 
+For AI-assisted work, treat `node_modules/prisma-php/dist/docs` as the installed Prisma PHP docs location for the active project version, and keep `AGENTS.md` in the project root aligned with that docs set.
+
 ## AI rule: read the structure docs first
 
 Before generating Prisma PHP files or folders, use this order:
 
 1. Read `prisma-php.json`.
-2. Decide whether the task belongs in `src/app`, `src/Lib`, `prisma`, `public`, or `settings`.
-3. Create routes from the route tree instead of editing `files-list.json`.
-4. Use `layouts-and-pages.md`, `route-handlers.md`, or `components.md` once the file location is known.
+2. Read the matching installed doc in `node_modules/prisma-php/dist/docs`.
+3. Read `AGENTS.md` for project-specific Prisma PHP rules.
+4. Decide whether the task belongs in `src/app`, `src/Lib`, `prisma`, `public`, `settings`, or the installed docs path.
+5. Create routes from the route tree instead of editing `files-list.json`.
+6. Use `layouts-and-pages.md`, `route-handlers.md`, or `components.md` once the file location is known.
 
 ## Folder and file conventions
 
@@ -26,10 +39,21 @@ Top-level folders are used to organize your application's source code, configura
 | ---------- | ----------------------------------------------------------------------------- |
 | `src/app`  | File-system based routing, pages, layouts, loading states, and route handlers |
 | `src/Lib`  | Application libraries, generated Prisma classes, auth, middleware, utilities  |
+| `ts`       | Frontend TypeScript modules and Vite entry files when `typescript` is enabled |
 | `public`   | Public web root, static files, CSS, JS, favicon, and public entry point       |
 | `prisma`   | Prisma schema, migrations, and seed scripts                                   |
 | `settings` | Project configuration such as paths, BrowserSync, and related setup           |
 
+### Installed framework docs
+
+Prisma PHP installs its framework docs inside `node_modules/prisma-php/dist/docs`.
+
+AI agents should treat that installed docs directory as the single source of truth for framework behavior in the active project version.
+
+| Path                                | Purpose                                                              |
+| ----------------------------------- | -------------------------------------------------------------------- |
+| `node_modules/prisma-php/dist/docs` | Installed Prisma PHP docs for the current project version and AI use |
+
 ### Top-level files
 
 These files are typically used to configure the app, manage dependencies, and define environment values.
@@ -39,6 +63,7 @@ These files are typically used to configure the app, manage dependencies, and de
 | `composer.json`        | PHP dependencies and autoloading                               |
 | `package.json`         | Frontend tooling and development scripts when used             |
 | `.env`                 | Environment variables                                          |
+| `AGENTS.md`            | Project-root AI guidance aligned with the installed docs set   |
 | `prisma/schema.prisma` | Main Prisma schema file                                        |
 | `public/index.php`     | Public entry point                                             |
 | `bootstrap.php`        | Application bootstrap and middleware registration when present |
@@ -69,6 +94,8 @@ For backend-only API projects, read `backend-only.md`.
 
 For Swagger and OpenAPI generation, read `swagger-docs.md`.
 
+For TypeScript frontend tooling, the root `ts/` directory, `ts/main.ts`, and npm-backed browser utilities, read `typescript.md`.
+
 ### Full-stack vs backend-only routing decision
 
 One of the most important capability flags is `backendOnly`.
@@ -236,6 +263,10 @@ Redirects are handled with `Request::redirect()`, which sends an HTTP `Location`
 
 ```txt
 prisma-php-project/
+├── node_modules/
+│   └── prisma-php/
+│       └── dist/
+│           └── docs/
 ├── prisma/
 │   ├── migrations/
 │   ├── schema.prisma
@@ -287,6 +318,7 @@ prisma-php-project/
 ├── composer.json
 ├── package.json
 ├── prisma-php.json
+├── AGENTS.md
 └── .env
 ```
 

package/dist/docs/pulsepoint.md

@@ -1,14 +1,22 @@
 ---
 title: PulsePoint Runtime Guide
 description: Learn how AI agents should use the current PulsePoint runtime contract, component script rules, and supported directives in Prisma PHP.
+related:
+  title: Related docs
+  description: Read the route, component, data-fetching, and TypeScript docs alongside the PulsePoint runtime contract.
+  links:
+    - /docs/pages-and-layouts
+    - /docs/import-component
+    - /docs/fetch-function
+    - /docs/typescript
 ---
 
-# PulsePoint Runtime Guide
-
 ## Purpose
 
 This file describes the PulsePoint runtime that is actually implemented in the current TypeScript source of this repo. Treat it as the working contract for AI-generated code.
 
+If a task involves `pp.state`, `pp.effect`, `pp-ref`, `pp-spread`, route-root scripts, imported partial runtime behavior, or current `pp-component` semantics, AI agents should read this page first and keep generated code aligned with the runtime implemented in this repo.
+
 Do not assume React, Vue, Svelte, JSX, or older PulsePoint docs.
 
 ## Runtime shape

package/dist/docs/typescript.md

@@ -0,0 +1,195 @@
+---
+title: TypeScript & NPM
+nav_title: TypeScript
+description: Learn how Prisma PHP uses the `typescript` feature flag so AI agents can place TypeScript in `ts/`, register browser helpers from `ts/main.ts`, and use them safely from PulsePoint component roots.
+related:
+  title: Related docs
+  description: Read the Prisma PHP docs that define feature flags, project updates, and PulsePoint component boundaries before generating TypeScript-aware examples.
+  links:
+    - /docs/commands
+    - /docs/upgrading
+    - /docs/project-structure
+    - /docs/pulsepoint
+    - /docs/components
+---
+
+Prisma PHP TypeScript support should follow the framework's Vite-backed frontend workflow, not ad hoc inline module imports inside `index.php`, `layout.php`, or imported partials.
+
+If a task involves the `typescript` flag in `prisma-php.json`, the root `ts/` directory, `ts/main.ts`, frontend npm packages, or using registered browser helpers inside PulsePoint templates and scripts, AI agents should read this page first and keep the implementation aligned with Prisma PHP's component boundary rules.
+
+## AI rule: read the TypeScript docs first
+
+Before generating, editing, or reviewing TypeScript-related frontend code, use this order:
+
+1. Read `./prisma-php.json` in a generated Prisma PHP app and confirm whether `typescript` is enabled.
+2. For an existing app, enable `typescript` first, then run `npx pp update project -y`.
+3. Keep reusable frontend TypeScript modules in the root `ts/` directory.
+4. Use `ts/main.ts` as the entry file that registers browser helpers for runtime use.
+5. Use those registered globals from template expressions and PulsePoint component scripts.
+6. Keep inline route or partial `<script>` blocks as plain JavaScript. Do not place `import` or `export` inside them.
+
+Do not guess from React, Vue, Next.js, or generic Vite projects alone. Prisma PHP still follows its own PulsePoint component and route-file rules.
+
+## Read this doc when you need
+
+- **the `typescript` feature flag in `prisma-php.json` or the `--typescript` create flag** -> `commands.md`, `upgrading.md`, and `typescript.md`
+- **where TypeScript files should live in a Prisma PHP app** -> `project-structure.md` and `typescript.md`
+- **how to use registered browser helpers inside a normal PulsePoint route root** -> `layouts-and-pages.md`, `pulsepoint.md`, and `typescript.md`
+- **how to use the same helpers inside an imported single-root partial** -> `components.md` and `typescript.md`
+- **installing npm packages for frontend utilities** -> `typescript.md`
+
+## When TypeScript is enabled
+
+When `typescript` is enabled in `prisma-php.json`, Prisma PHP can use a Vite-powered frontend TypeScript workflow.
+
+The practical rules are:
+
+- keep browser-side TypeScript modules in `ts/`
+- use `ts/main.ts` as the registration entry file
+- install npm packages normally
+- expose the browser helpers you want to call from templates or PulsePoint scripts
+- keep inline PulsePoint scripts as plain JavaScript and call the registered globals from there
+
+## Enable TypeScript in a new or existing app
+
+### New project
+
+```bash package="npm"
+npx create-prisma-php-app my-app --typescript
+```
+
+### Existing project
+
+Enable the feature in `prisma-php.json`, then refresh the project files.
+
+```json filename="prisma-php.json"
+{
+  "projectName": "my-app",
+  "typescript": true
+}
+```
+
+```bash package="npm"
+npx pp update project -y
+```
+
+For broader project refresh guidance, read `upgrading.md`.
+
+## The `ts/` directory
+
+For organization and reuse, keep frontend TypeScript logic in the root `ts/` directory.
+
+This keeps module code out of route files and makes the frontend entry pipeline explicit.
+
+Example layout:
+
+```txt
+ts/
+├── date-utils.ts
+├── global-functions.ts
+├── main.ts
+└── to-money.ts
+```
+
+Example utility:
+
+```ts filename="ts/to-money.ts"
+export function toMoney(value: number): string {
+  return `$${value.toFixed(2)}`;
+}
+```
+
+## Use any npm package
+
+Because this workflow is Vite-backed, you can install npm packages and import them directly into files under `ts/`.
+
+```bash package="npm"
+npm install date-fns
+```
+
+```ts filename="ts/date-utils.ts"
+import { format } from "date-fns";
+
+export function getToday(): string {
+  return format(new Date(), "yyyy-MM-dd");
+}
+```
+
+## Register helpers in `ts/main.ts`
+
+Use the TypeScript entry file to register the browser helpers you want available globally.
+
+```ts filename="ts/main.ts"
+import { createGlobalSingleton } from "./global-functions";
+import { getToday } from "./date-utils";
+import { toMoney } from "./to-money";
+
+createGlobalSingleton("getToday", getToday);
+createGlobalSingleton("toMoney", toMoney);
+```
+
+After registration, those helpers can be used from Prisma PHP template expressions and PulsePoint component scripts without adding `import` statements inside the route file itself.
+
+## Important PulsePoint boundary
+
+Prisma PHP inline component scripts are plain JavaScript, not module files.
+
+That means the right split is:
+
+- write reusable module logic in `ts/`
+- register the pieces you need from `ts/main.ts`
+- call those registered helpers from the inline PulsePoint script inside the component root
+- do not place `import` or `export` inside the inline route or imported-partial script
+
+When the UI lives in `index.php` or nested `layout.php`, keep the normal Prisma PHP route structure:
+
+1. PHP first
+2. one parent HTML element
+3. `pp-component` on that route root when PulsePoint is present
+4. one `<script>` block as the last child inside that same root element
+
+When the UI lives in an imported partial rendered through `ImportComponent::render(...)`, keep exactly one root element and place any component-local `<script>` inside that root. Do not manually add `pp-component` inside the imported partial source.
+
+## Usage inside a PulsePoint route
+
+This example keeps the route in the current Prisma PHP single-root component pattern while calling helpers registered from `ts/main.ts`.
+
+```php filename="src/app/index.php"
+<?php
+
+use PP\MainLayout;
+
+MainLayout::$title = 'TypeScript Helpers';
+MainLayout::$description = 'Use registered TypeScript helpers from a PulsePoint route.';
+?>
+
+<section pp-component="typescript-demo-page">
+    <h1>TypeScript helpers</h1>
+    <p>Today: {getToday()}</p>
+    <p>Catalog price: {toMoney(1234.56)}</p>
+    <p>Discounted price: {discountedPrice}</p>
+
+    <button onclick="applyDiscount()">Apply discount</button>
+
+    <script>
+        const [discountedPrice, setDiscountedPrice] = pp.state(toMoney(15245));
+
+        function applyDiscount() {
+            setDiscountedPrice(toMoney(11999.5));
+        }
+    </script>
+</section>
+```
+
+The helper calls stay available in both template expressions and the inline PulsePoint script, while the route still follows the documented Prisma PHP component boundary rules.
+
+## AI rules for TypeScript tasks
+
+- inspect `prisma-php.json` first and confirm whether `typescript` is enabled
+- for existing apps, enable the feature and run `npx pp update project -y` before assuming the TypeScript scaffold exists
+- keep reusable module code in `ts/`
+- register browser helpers from `ts/main.ts`
+- use npm packages through normal imports inside `ts/` files
+- do not place `import` or `export` inside inline PulsePoint scripts in `index.php`, `layout.php`, or imported partials
+- keep normal route files in the single-root PulsePoint pattern with the `<script>` as the last child inside the route root
+- keep `ImportComponent` partials in the single-root pattern and let Prisma PHP inject `pp-component` there automatically

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prisma-php",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Prisma PHP tooling",
   "main": "index.js",
   "scripts": {