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

prisma-php 0.0.3 → 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 (6) hide show

package/.github/copilot-instructions.md +24 -0
package/dist/docs/components.md +38 -3
package/dist/docs/index.md +3 -2
package/dist/docs/layouts-and-pages.md +5 -4
package/dist/docs/pulsepoint.md +135 -397
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/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/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 normal interactive full-stack page work, default to PulsePoint plus `pp.fetchFunction(...)` unless the user explicitly asks for a PHP-only interaction style. 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. _/}
+{/_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!
@@ -71,7 +71,8 @@ Do **not** default to PHP-only interaction flows for normal reactive UI work unl
 - 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; 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, and keep route content inside a single parent HTML element
+- 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

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

@@ -70,10 +70,11 @@ In practice, that means:
 - 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.
+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>`.
-- In nested `layout.php`, wrap the shared layout UI and `<?= MainLayout::$children; ?>` in one parent element.
+- 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:
@@ -210,7 +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;`.
+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

package/dist/docs/pulsepoint.md CHANGED Viewed

@@ -1,474 +1,212 @@
-# PulsePoint: always read the official docs before generating code
+# PulsePoint Runtime Guide
-> Purpose: eliminate guessing and make AI-generated PulsePoint code accurate, copy-pasteable, and aligned with the real runtime.
->
-> Scope: this document covers the **core PulsePoint runtime** only — browser-side state, effects, refs, and markup directives. It does **not** assume any specific backend or server framework.
->
-> Official docs: [https://pulsepoint.tsnc.tech/llms](https://pulsepoint.tsnc.tech/llms)
->
-> Version: 3.0.0
+## Purpose
----
+This file describes the PulsePoint runtime that is actually implemented in the current TypeScript source of this repo. Use it as the working contract for AI-generated code.
-## Read the PulsePoint docs first
+If `src/` is available, read it first. If the app only exposes a plain HTML page plus a minified or bundled runtime loaded by a script tag, inspect those artifacts instead and follow the same behavior. Do not assume React, Vue, Svelte, or older PulsePoint docs.
-Before generating, editing, or reviewing any PulsePoint code, read the official PulsePoint docs:
+## What the runtime actually does
-```txt
-https://pulsepoint.tsnc.tech/llms
-```
-Treat the PulsePoint docs as the source of truth for:
-- supported runtime APIs
-- supported directives and markup behavior
-- syntax rules
-- state and effect patterns
-- ref usage
-- limitations and forbidden patterns
-Do not rely on assumptions from React, Vue, Alpine, Svelte, Livewire, jQuery, or any other framework.
-If the docs do not show a feature or API, do **not** invent it.
----
-## Prisma PHP integration rule
-When PulsePoint is used inside a Prisma PHP application, the default full-stack pattern is:
-- PulsePoint for reactive browser state and UI updates
-- `pp.fetchFunction(...)` for frontend-to-PHP server calls
-- `#[Exposed]` on PHP functions or methods that the frontend should be allowed to call
-- `PP\Validator` on the PHP side for authoritative input validation and normalization
-For normal interactive Prisma PHP page work, AI should treat this as the **default implementation path**, not as an optional enhancement. Choose a more PHP-only interaction style only when the user explicitly asks for it or when the route is intentionally non-reactive.
-Do not invent parallel client/server patterns when the built-in Prisma PHP RPC flow already fits the task. In typical Prisma PHP page work, prefer PulsePoint plus `pp.fetchFunction(...)` over ad hoc API wiring, manual JSON fetch boilerplate, or PHP-only interaction patterns that the user did not request.
-If the PulsePoint code lives inside Prisma PHP `index.php` or `layout.php`, also follow the route-file structure rules from `layouts-and-pages.md`: PHP first, HTML second, one `<script>` block last, and a single parent HTML element for normal route content.
-Use `route.php` only when you explicitly need a standalone endpoint such as a webhook, public JSON route, external integration endpoint, or other no-view handler. Do not move normal route-local interactivity into `route.php` by default.
-## Validation boundary
-PulsePoint can help with local UX such as:
-- showing inline hints
-- disabling submit buttons
-- rendering field-level error messages
-- debouncing live validation requests
-But the final validation still belongs on the PHP side.
-In Prisma PHP, the default boundary is:
-- **PulsePoint** for local UI state and feedback
-- **`pp.fetchFunction(...)`** for sending data to PHP
-- **`PP\Validator`** for authoritative backend validation
-Do not present browser-only checks as the final source of truth.
----
-## What PulsePoint is responsible for
-PulsePoint is the **browser-side reactive runtime**.
-It is responsible for UI interactivity such as:
-- local reactive state
-- reactive effects
-- DOM refs
-- list rendering
-- attribute spreading
-- simple interactive bindings
-PulsePoint is **not** the backend.
-That means an AI agent must keep these concerns separate:
-- **PulsePoint docs** decide how frontend runtime code should be written.
-- **Project/backend docs** decide how data is loaded, validated, saved, authenticated, or routed on the server.
----
-## Allowed runtime surface
-Only use the runtime surface explicitly allowed here unless the official docs say otherwise.
-### Core JavaScript API
-1. `pp.state<T>(initial)` → `[state, setState]`
-2. `pp.ref<T>(initial: T | null)`
-3. `pp.effect(fn: () => void | (() => void), deps?: Dependency[])`
-### Markup directives
+PulsePoint is a browser-side component runtime. It renders HTML, binds state and events, and morphs the DOM in place.
-1. `pp-for` _(only on `<template>`)_
-2. `pp-spread`
-3. `pp-ref`
+A component root is any element with `pp-component`.
-If a symbol is not listed above and is not documented in the official PulsePoint docs, treat it as unsupported.
+## Component roots and scripts
----
-## Decision rules for AI agents
-When working with PulsePoint, follow these rules:
-1. Read the official PulsePoint docs before making runtime decisions.
-2. Do not invent undocumented helpers, directives, lifecycle APIs, or magic globals.
-3. Keep backend assumptions out of PulsePoint-only examples.
-4. Prefer simple, explicit patterns over framework-inspired abstractions.
-5. Generate code that is valid immediately, not pseudo-code.
-6. When uncertain, reduce scope to documented PulsePoint primitives.
-7. If a project also includes framework-specific rules, apply them **after** the PulsePoint docs for backend concerns, but keep PulsePoint runtime syntax aligned with the official PulsePoint docs.
----
-## Priority order
-When generating code that uses PulsePoint, use this order of truth:
-1. The user’s explicit request
-2. The official PulsePoint docs: `https://pulsepoint.tsnc.tech/llms`
-3. Project-specific agent rules or local project docs
-4. Existing project code and structure
-5. General framework knowledge
-If any assumption conflicts with the official PulsePoint docs, follow the PulsePoint docs.
----
-## File layout rules
-For PulsePoint runtime code, keep a predictable layout.
-### Standalone runtime snippet order
-1. HTML markup first
-2. One `<script>` block at the bottom
+- Each component root may contain one inline `<script type="text/pp">` block for component logic.
+- The script is plain JavaScript, not a module. Do not use `import` or `export` inside it.
+- Top-level bindings from the script are exported automatically to the template. Do not manually `return { ... }`.
+- Top-level `const`, `let`, `function`, and supported destructuring patterns become template bindings.
+- `pp.props` contains the current prop bag for the component.
+- `children` contains the component's initial inner HTML.
+- Nested `pp-component` roots are boundaries and are not flattened by a parent component.
 Example:
 ```html
-<ul>
-  <template pp-for="user in users">
-    <li key="{user.id}">{user.name}</li>
-  </template>
-</ul>
-<script>
-  const [users, setUsers] = pp.state([
-    { id: 1, name: "Alice" },
-    { id: 2, name: "Bob" },
-  ]);
-</script>
-```
-### Prisma PHP route file order
-When PulsePoint is used inside Prisma PHP `index.php` or `layout.php` files, keep this order:
-1. PHP
-2. HTML
-3. SCRIPT
-Example:
-```php filename="src/app/dashboard/index.php"
-<?php
-$title = "Dashboard";
-?>
-<section class="dashboard-page">
-  <h1><?= htmlspecialchars($title); ?></h1>
+<div pp-component="counter-card">
+  <h2>{title}</h2>
   <p>Count: {count}</p>
   <button onclick="setCount(count + 1)">Increment</button>
-</section>
-<script>
-  const [count, setCount] = pp.state(0);
-</script>
-```
-Additional Prisma PHP route rules:
-- `index.php` and nested `layout.php` should render a single parent HTML element.
-- Treat them like single-root route views; do not emit multiple sibling root nodes for normal PulsePoint pages.
-- The root `layout.php` is the only file that should define `<html>`, `<head>`, and `<body>`.
-- When the root layout uses PulsePoint, keep the script block near the end of `<body>` and keep `MainLayout::$children;` inside one clear wrapper element.
-Rules:
-- Use **exactly one** `<script>` block per page, layout, or component unless the project explicitly requires something else.
-- Place the script block **after** the markup. In Prisma PHP route files, that means after the HTML section.
-- JavaScript should only reference data that already exists when the script runs.
-- Do not scatter PulsePoint runtime logic across multiple disconnected script blocks unless the docs or project structure explicitly requires it.
----
+  <script type="text/pp">
+    const { title } = pp.props;
+    const [count, setCount] = pp.state(0);
+    const doubled = count * 2;
-## Conditionals and booleans
-Prefer visibility toggles instead of complex conditional markup.
-### Preferred
-```html
-<div hidden="{!isOpen}">Shown when open</div>
-<div hidden="{isOpen}">Shown when closed</div>
-```
-### Text or attribute ternaries
-```html
-<span class="{isActive ? 'text-green-600' : 'text-red-600'}">
-  {isActive ? 'Active' : 'Inactive'}
-</span>
-```
-### Boolean attributes
-```html
-<input type="checkbox" checked="{isActive}" />
+    function reset() {
+      setCount(0);
+    }
+  </script>
+</div>
 ```
-String branches in ternaries must be quoted correctly.
+## Hooks exposed through `pp`
-- Correct: `{isActive ? 'text-blue-500' : 'text-gray-500'}`
-- Invalid: `{isActive ? text-blue-500' : 'text-gray-500'}`
+- `pp.state(initial)` returns `[value, setValue]`.
+- `pp.effect(callback, deps?)` runs after render and can return cleanup.
+- `pp.layoutEffect(callback, deps?)` runs synchronously after DOM mutation.
+- `pp.ref(initialValue?)` returns `{ current }`.
+- `pp.memo(factory, deps)` memoizes a computed value.
+- `pp.callback(callback, deps)` memoizes a function.
+- `pp.reducer(reducer, initialState)` returns `[state, dispatch]`.
+- `pp.portal(ref, target?)` portals a ref-managed element into a target.
+- `pp.props` exposes the current props.
----
+Notes:
-## Refs with `pp-ref`
+- `pp.state` setters accept either a value or an updater function.
+- `pp.effect` and `pp.layoutEffect` use dependency arrays like React, but only the hooks listed here exist.
+- Keep template-facing bindings at the top level so the AST-based exporter can see them.
-### Single element ref
+## Template expressions and attributes
-```html
-<input type="text" pp-ref="{nameInput}" />
-<button onclick="nameInput.current?.focus()">Focus</button>
-<script>
-  const nameInput = pp.ref(null);
-</script>
-```
+- Use `{expression}` in text nodes and attribute values.
+- Pure bindings like `value="{count}"` are evaluated as expressions.
+- Mixed text like `class="card {isActive ? 'active' : ''}"` is supported.
+- Boolean attributes are normalized for supported boolean names.
+- Use `pp-spread="{...attrs}"` to spread one object expression into attributes.
+- Use plain `key` for keyed diffing. `pp-key` is not implemented in the current source.
-### Dynamic ref registration
+Example:
 ```html
-<ul>
-  <template pp-for="item in items">
-    <li key="{item.id}">
-      <input pp-ref="{registerRef(item.id)}" hidden="{editingId !== item.id}" />
-      <button onclick="setEditingId(item.id)">Edit</button>
-    </li>
-  </template>
-</ul>
+<button pp-spread="{...buttonAttrs}" hidden="{isLoading}">Save</button>
-<script>
-  const [items, setItems] = pp.state([
-    { id: 1, name: "Task A" },
-    { id: 2, name: "Task B" },
-  ]);
-  const [editingId, setEditingId] = pp.state(null);
-  const itemRefs = new Map();
-  const registerRef = (id) => (el) => {
-    if (el) itemRefs.set(id, el);
-    else itemRefs.delete(id);
+<script type="text/pp">
+  const buttonAttrs = {
+    class: "btn btn-primary",
+    "aria-label": "save",
   };
-  pp.effect(() => {
-    if (editingId && itemRefs.has(editingId)) {
-      itemRefs.get(editingId).focus();
-    }
-  }, [editingId]);
+  const isLoading = false;
 </script>
 ```
-Rules:
-- Initialize refs with `pp.ref(null)`.
-- Null-check ref access where appropriate.
-- Use refs for DOM access and imperative behavior, not as general reactive state storage.
----
-## Spread with `pp-spread`
+## Refs
-### Basic usage
-```html
-<button pp-spread="{...btn}">Submit</button>
-<script>
-  const [btn] = pp.state({
-    class: "px-3 py-2 rounded-md",
-    "aria-label": "submit",
-  });
-</script>
-```
+- Use `pp-ref="nameInput"` when the value is a ref object or callback already in scope.
+- Use `pp-ref="{registerRef(id)}"` when you need a dynamic expression.
+- `pp.ref(null)` is the normal way to create a ref object.
+- The runtime generates `data-pp-ref` internally. Do not author it.
+- Do not author `pp-event-owner`, `pp-owner`, or `pp-dynamic-*` attributes by hand.
-### Multiple spreads
+Example:
 ```html
-<input pp-spread="{...base, ...validation}" placeholder="Name" />
-<script>
-  const [base] = pp.state({ class: "input-base", required: true });
-  const [validation] = pp.state({ pattern: "[A-Za-z]+" });
-</script>
+<div pp-component="focus-box">
+  <input pp-ref="nameInput" />
+  <button onclick="nameInput.current?.focus()">Focus</button>
+  <script type="text/pp">
+    const nameInput = pp.ref(null);
+  </script>
+</div>
 ```
-Rules:
-- Later spreads override earlier spreads.
-- Explicit attributes on the element override spread values.
+## Lists and loops
----
+- Use `pp-for` only on `<template>`.
+- Supported forms are `item in items` and `(item, index) in items`.
+- The collection must be an array. Non-arrays are treated as empty lists.
+- Loop content can contain interpolations, events, refs, and nested components.
+- Use stable unique `key` values on repeated elements.
+- Duplicate keys can trigger warnings, so do not use random keys.
-## Lists with `pp-for`
+Example:
 ```html
 <ul>
-  <template pp-for="todo in todos">
+  <template pp-for="(todo, index) in todos">
     <li key="{todo.id}">
-      {todo.title}
+      {index + 1}. {todo.title}
       <button onclick="removeTodo(todo.id)">Remove</button>
     </li>
   </template>
 </ul>
-<script>
+<script type="text/pp">
   const [todos, setTodos] = pp.state([
     { id: 1, title: "First task" },
     { id: 2, title: "Second task" },
   ]);
   function removeTodo(id) {
-    setTodos(todos.filter((item) => item.id !== id));
+    setTodos(todos.filter((todo) => todo.id !== id));
   }
 </script>
 ```
-Rules:
-- Use `pp-for` only on `<template>`.
-- Always use stable keys such as IDs or stable indices.
-- Never use random keys.
-- Prefer immutable updates through setters.
----
-## Effects with `pp.effect`
-```html
-<script>
-  pp.effect(() => console.log("Any change"));
-  pp.effect(() => {
-    return () => {
-      // cleanup
-    };
-  }, []);
-  const [count, setCount] = pp.state(0);
-  pp.effect(() => {
-    console.log("count", count);
-  }, [count]);
-</script>
-```
-Rules:
+## Events
-- Use `[]` for one-time setup and cleanup.
-- Use dependency arrays to react to specific state changes.
-- Avoid unconditional setter calls inside effects.
-- Guard effect-driven updates to prevent loops.
+- Use native `on*` attributes such as `onclick`, `oninput`, and `onsubmit`.
+- Event values may be raw code or wrapped in `{...}`.
+- The runtime injects `event`, `e`, `$event`, `target`, `currentTarget`, and `el`.
+- Do not use hyphenated event attrs like `on-click`.
+- Handlers are rebound after DOM morphing, so do not assume one-time binding.
----
+## SPA, loading, and navigation helpers
-## Input binding patterns
+- `body[pp-spa="true"]` enables client-side navigation interception.
+- `a[pp-spa="false"]` disables interception for that link.
+- `pp-loading-content="true"` marks the page region that gets swapped during navigation.
+- `pp-loading-url` selects route-specific loading states.
+- `pp-loading-transition` accepts JSON with `fadeIn` and `fadeOut` timing values.
+- `pp-reset-scroll="true"` resets scroll positions during navigation.
-### Checkbox
+The runtime also exposes navigation and bridge helpers through `pp`:
-```html
-<input
-  type="checkbox"
-  checked="{isActive}"
-  onchange="setIsActive(event.target.checked)"
-/>
-<script>
-  const [isActive, setIsActive] = pp.state(false);
-</script>
-```
+- `pp.mount()`
+- `pp.redirect(url)`
+- `pp.fetchFunction(name, data?, optionsOrAbort?)`
+- `pp.enablePerf()`
+- `pp.disablePerf()`
+- `pp.getPerfStats()`
+- `pp.resetPerfStats()`
-### Text input
+Notes:
-```html
-<input type="text" value="{name}" oninput="setName(event.target.value)" />
-<script>
-  const [name, setName] = pp.state("");
-</script>
-```
+- `pp.redirect()` uses SPA navigation when it is enabled and the URL is same-origin; otherwise it falls back to normal navigation.
+- `pp.fetchFunction()` is the runtime RPC bridge. It posts to the current route, attaches the wire headers the backend expects, and can switch to FormData for files, report upload progress, abort the previous request, or stream responses when supported.
+- The bundle mounts the runtime automatically once the global `pp` singleton is accessed after DOMContentLoaded, but `pp.mount()` exists if you want to trigger it explicitly.
-Rules:
+## Plain HTML bundle usage
-- Inputs should read from state.
-- Inputs should write back through explicit setters.
-- Avoid mixing manual DOM querying with reactive state for the same value.
+When the app is shipped as plain HTML plus a minified bundle:
----
+- Keep the component markup in the HTML.
+- Load the bundle with a script tag after the markup or with `defer`.
+- Keep component logic inside `<script type="text/pp">` blocks in the HTML.
+- Do not assume access to the TypeScript source at runtime.
-## Forbidden patterns
+## What to avoid
-Do not generate these unless the official PulsePoint docs explicitly document them:
+Do not generate these unless the current source explicitly supports them:
-1. Undocumented runtime APIs
-2. Undocumented directives
-3. `pp-for` on non-`<template>` elements
-4. Random keys in rendered lists
-5. Multiple scattered script blocks for normal PulsePoint pages
-6. Direct DOM mutation for stateful UI that should be reactive
-7. Backend-specific assumptions in PulsePoint-only snippets
-8. Syntax copied from another framework without PulsePoint documentation support
+- `pp-context`
+- `pp-key`
+- `data-pp-ref`
+- `pp-owner`
+- `pp-event-owner`
+- `pp-dynamic-script`
+- `pp-dynamic-meta`
+- `pp-dynamic-link`
+- plain `<script>` for component logic inside a component root
+- React, Vue, Svelte, or JSX-style component patterns that are not implemented here
+- made-up hooks, directives, or globals not present in the current TypeScript source
----
+## AI checklist
-## How AI should respond when PulsePoint is involved
+When working on PulsePoint code, follow this order:
-When a user asks for PulsePoint code, the AI should:
-1. Check the official PulsePoint docs first.
-2. Keep the solution inside documented PulsePoint primitives.
-3. Separate frontend PulsePoint behavior from backend implementation details.
-4. Avoid claiming a PulsePoint feature exists unless the docs support it.
-5. Prefer working examples that are ready to paste into a project.
-6. If the code lives in `index.php` or `layout.php`, use PHP, then HTML, then one `<script>` block, and keep a single parent HTML element for route content.
-A good PulsePoint answer should feel:
-- minimal
-- explicit
-- backend-agnostic when appropriate
-- syntactically valid
-- faithful to the documented runtime
----
+- Use the current TypeScript source when it is available.
+- If only HTML plus a minified bundle exists, inspect those artifacts and follow the runtime behavior implemented there.
+- Keep template-facing variables at the top level of the component script.
+- Use only the hooks, directives, and attributes listed above.
+- Keep `pp-for` on `<template>` and use plain `key`.
+- Use refs and events as implemented, not as they work in another framework.
+- Avoid generating internal runtime attributes.
 ## Final reminder
-If you are generating, reviewing, or refactoring PulsePoint code, do **not** guess.
-Read the official docs first:
-```txt
-https://pulsepoint.tsnc.tech/llms
-```
-Then generate code using documented PulsePoint behavior only.
+If a feature is not implemented in the current runtime source, do not invent it.

package/package.json CHANGED Viewed

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