prisma-php 0.0.11 → 0.0.13

package/dist/docs/swagger-docs.md

@@ -34,10 +34,14 @@ Before enabling or regenerating Swagger docs, use this order:
 
 1. Inspect `prisma-php.json` for `swaggerDocs` and `backendOnly`.
 2. Read `backend-only.md`, `route-handlers.md`, and `prisma-php-orm.md` as needed for the surrounding API workflow.
-3. Use `npm run create-swagger-docs` for the documented generation flow.
+3. Use `npm run create-swagger-docs` for the documented on-demand generation flow.
 4. Inspect `settings/prisma-schema-config.json` before changing output paths or generation modes.
 5. Do not treat Swagger generation as a substitute for ORM migrations or route implementation.
 
+Unlike generated Tailwind or TypeScript build/watch scripts, Swagger generation is not the normal framework-managed step that runs as part of everyday `npm run dev` or `npm run build` work.
+
+AI agents should treat `npm run create-swagger-docs` as an explicit documentation or contract-generation action and run it only when Swagger output actually needs to be created or refreshed.
+
 ## When Swagger docs are worth enabling
 
 Enable Swagger docs when you need a stable machine-readable contract for the API.
@@ -80,6 +84,10 @@ That JSON file is the handoff point for tools such as:
 
 Prisma PHP's Swagger workflow supports generating documentation for models from `schema.prisma`.
 
+Use this command intentionally when your OpenAPI output needs to be updated.
+
+Do not confuse it with framework-managed development scripts such as `npm run dev` or asset build orchestration through `npm run build`.
+
 ```bash package="npm"
 npm run create-swagger-docs
 npm run create-swagger-docs Order
@@ -135,7 +143,7 @@ For API-oriented Prisma PHP work, a practical Swagger workflow is:
 
 1. update `schema.prisma`
 2. run the normal ORM workflow when the schema changed
-3. regenerate Swagger docs
+3. regenerate Swagger docs only when the contract output needs to be refreshed
 4. inspect `src/app/swagger-docs/apis/pphp-swagger.json`
 5. regenerate external clients if the contract changed
 

package/dist/docs/typescript.md

@@ -0,0 +1,202 @@
+---
+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`.
+
+After TypeScript scaffolding exists, ordinary local work should still start from the framework-managed entry points:
+
+- `npm run dev` for normal development
+- `npm run build` when you intentionally want a production-style asset build
+
+Do not default to `npm run ts:watch` or `npm run ts:build` after routine TypeScript edits unless you intentionally need to isolate the frontend bundle step.
+
+## 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/dist/docs/upgrading.md

@@ -47,6 +47,17 @@ npx pp update project -y
 
 This ensures the update process applies the correct files, dependencies, and project structure for the features you selected.
 
+For feature flags such as `tailwindcss`, `typescript`, `websocket`, and `mcp`, the updater's job is to refresh the generated files and scripts that the framework expects.
+
+After that, AI agents should not default to telling users to manually run each feature-specific package script one by one.
+
+For ordinary local verification after an update, prefer:
+
+- `npm run dev` for the normal development workflow
+- `npm run build` when you intentionally want a production-style asset build
+
+Use lower-level scripts such as Tailwind, TypeScript, WebSocket, or MCP commands only when isolating a specific part of the toolchain, debugging, or running a feature-specific workflow on purpose.
+
 If the feature you are enabling is API-focused, read `backend-only.md` for `backendOnly` usage and `swagger-docs.md` for `swaggerDocs` generation workflow details.
 
 ## Typical upgrade flow
@@ -155,7 +166,7 @@ After updating your project, verify the following:
 
 - Your enabled features in `prisma-php.json` match the current project requirements.
 - Dependencies installed correctly.
-- Local development still runs as expected.
+- Local development still runs as expected, normally through `npm run dev` rather than individual watcher scripts.
 - Any custom files listed in `excludeFiles` were preserved.
 - Database and generated ORM classes are in sync if schema changes were included.
 

package/dist/docs/websocket.md

@@ -84,6 +84,10 @@ The broader Prisma PHP project structure docs also show a development helper tha
 
 - `settings/restart-websocket.ts`
 
+Some Prisma PHP setups also wire websocket restart behavior into `npm run dev`.
+
+AI should inspect the current `package.json` before telling users to run `npm run websocket` manually, and should prefer the normal development flow unless websocket startup needs to be isolated or debugged on purpose.
+
 Important casing rule:
 
 The official page may show lowercase path examples such as `src/lib/websocket`, but Prisma PHP project structure docs use `src/Lib`, and this repo's guidance expects application libraries under `src/Lib`.

package/package.json

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