npm - prisma-php - Versions diffs - 0.0.7 → 0.0.9 - Mend

prisma-php 0.0.7 → 0.0.9

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

package/.github/copilot-instructions.md +4 -3
package/dist/docs/components.md +15 -15
package/dist/docs/index.md +11 -11
package/dist/docs/layouts-and-pages.md +15 -15
package/dist/docs/project-structure.md +9 -10
package/dist/docs/pulsepoint.md +135 -50
package/package.json +1 -1

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

@@ -7,15 +7,16 @@
 ## Route File Conventions
-- For PulsePoint-aware `index.php` and `layout.php`, keep file order as PHP, then HTML, then one `<script>` block.
+- For PulsePoint-aware `index.php` and nested `layout.php`, keep file order as PHP first, then one parent HTML element; keep the PulsePoint `<script>` as the last child inside that same root element.
 - `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.
+- When a route or nested layout uses PulsePoint, put `pp-component` on that single root element and keep any route-local `<script>` inside it.
+- Only the root `layout.php` should define `<html>`, `<head>`, and `<body>`. When PulsePoint is present, keep `MainLayout::$children;` and any `<script>` inside one clear wrapper.
 ## 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.
+- 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

package/dist/docs/components.md CHANGED Viewed

@@ -86,7 +86,7 @@ For a normal route file such as `src/app/index.php` or nested `layout.php`, use
 1. PHP
 2. one parent HTML element for the route content
-3. one `<script>` block after that parent element
+3. when PulsePoint is present, keep one `<script>` block as the last child inside that same root element
 Example route-file pattern:
@@ -96,14 +96,13 @@ Example route-file pattern:
 $title = 'Dashboard';
 ?>
-<section class="dashboard-page">
+<section pp-component="dashboard-page">
     <h1><?= htmlspecialchars($title) ?></h1>
     <p>Count: {count}</p>
+    <script>
+        const [count, setCount] = pp.state(0);
+    </script>
 </section>
-<script>
-    const [count, setCount] = pp.state(0);
-</script>
 ```
 That is the correct route-page pattern. It is documented in `layouts-and-pages.md`, not in `ImportComponent`.
@@ -117,11 +116,11 @@ Correct imported-partial pattern:
 ```php filename="src/app/inc/SearchBox.php"
 <?php
-$title = 'Search';
+// PHP Code
 ?>
-<div class="rounded-lg border bg-card p-4" pp-component="search-box">
-    <h2 class="font-medium"><?= htmlspecialchars($title) ?></h2>
+<div class="rounded-lg border bg-card p-4">
+    <h2 class="font-medium">Search</h2>
     <input value="{query}" oninput="{(e) => setQuery(e.target.value)}" />
     <script>
         console.log('Search component ready');
@@ -134,11 +133,11 @@ Incorrect imported-partial pattern:
 ```php filename="src/app/inc/SearchBox.php"
 <?php
-$title = 'Search';
+// PHP Code
 ?>
 <section class="rounded-lg border bg-card p-4">
-    <h2 class="font-medium"><?= htmlspecialchars($title) ?></h2>
+    <h2 class="font-medium">Search</h2>
 </section>
 <script>
@@ -167,6 +166,7 @@ Why this is invalid:
 - 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
+- for normal PulsePoint-aware route files, author `pp-component` on the single route root and keep the `<script>` inside that root
 - do not apply the imported-partial rule to normal route files
 - do not apply the normal route-file pattern to imported partials
@@ -377,13 +377,13 @@ ImportComponent::render(APP_PATH . '/inc/UserCard.php', [
 use PP\ImportComponent;
 ?>
-<div class="space-y-4">
+<div pp-component="search-shell">
     <?php ImportComponent::render(APP_PATH . '/inc/SearchBox.php', [
         'query' => '{query}',
         'setQuery' => '{setQuery}',
     ]); ?>
-    <script type="text/pp">
+    <script>
         const [query, setQuery] = pp.state('');
     </script>
 </div>
@@ -416,7 +416,7 @@ $title = 'Search';
 <div class="rounded-lg border bg-card p-4">
     <h2 class="font-medium"><?= $title ?></h2>
     <input value="{query}" oninput="{(e) => setQuery(e.target.value)}" />
-    <script type="text/pp">
+    <script>
         console.log('Search component ready');
     </script>
 </div>
@@ -433,7 +433,7 @@ $title = 'Search';
 <section class="rounded-lg border bg-card p-4">
     <h2 class="font-medium"><?= $title ?></h2>
 </section>
-<script type="text/pp">
+<script>
     console.log('This script is a second root element');
 </script>
 ```

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 normal PulsePoint-aware route files such as `index.php` and nested `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 rendered with `ImportComponent::render(...)`, keep exactly one root element and place any component-local `<script>` inside that root because Prisma PHP uses that root as the component boundary where serialized props and `pp-component` attach. 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._/}
+{/_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 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._/}
 Welcome to the Prisma PHP documentation!
@@ -55,7 +55,7 @@ For a normal route file such as `src/app/index.php` or nested `layout.php`, use:
 1. PHP
 2. one parent HTML element
-3. one `<script>` block after that parent element
+3. when PulsePoint is present, keep one `<script>` block as the last child inside that same root element
 Example:
@@ -68,14 +68,13 @@ MainLayout::$title = 'Todos';
 MainLayout::$description = 'Track tasks and view the current item count.';
 ?>
-<section>
+<section pp-component="todos-page">
     <h1>Todos</h1>
     <p>Count: {count}</p>
+    <script>
+        const [count, setCount] = pp.state(0);
+    </script>
 </section>
-<script>
-    const [count, setCount] = pp.state(0);
-</script>
 ```
 For SEO metadata, prefer `MainLayout::$title` and `MainLayout::$description` instead of relying on a local heading variable alone.
@@ -97,7 +96,7 @@ Example:
 ?>
-<div class="rounded-lg border p-4" pp-component="search-box">
+<div pp-component="search-box">
     <h2>Search</h2>
     <input value="{query}" />
     <script>
@@ -134,9 +133,10 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 - 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, 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 and keep any partial-local `<script>` inside that root 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 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
+- do not manually add `pp-component` inside imported partial source; Prisma PHP injects it there
 - 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

@@ -61,20 +61,21 @@ Only shift to a more PHP-only pattern when the user explicitly asks for it or wh
 When `index.php` or `layout.php` includes PulsePoint, keep the file in this order:
 1. PHP
-2. HTML
-3. SCRIPT
+2. one parent HTML element
+3. keep the PulsePoint `<script>` as the last child inside that root element
 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
+- render the route markup inside one parent element after the PHP block
+- when PulsePoint is present, put `pp-component` on that single route or layout root
+- place one PulsePoint `<script>` block at the bottom of that same root element
 For the HTML portion, keep a **single parent HTML tag** around the route content. 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 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.
-- 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.
+- 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; ?>`, and keep any PulsePoint `<script>` inside that same wrapper when PulsePoint behavior is present.
 ### Important distinction: route files vs imported partials
@@ -84,7 +85,7 @@ For **normal route files** such as `src/app/index.php` and nested `layout.php`,
 1. PHP
 2. one parent HTML element for the rendered route UI
-3. one `<script>` block after that parent element
+3. when PulsePoint is present, keep one `<script>` block as the last child inside that same root element
 Correct route-file pattern:
@@ -99,20 +100,19 @@ MainLayout::$title = 'Todos';
 MainLayout::$description = 'Track tasks and view the current item count.';
 ?>
-<section class="space-y-4">
+<section pp-component="todos-page">
     <h1>Todos</h1>
     <p>Count: {count}</p>
+    <script>
+        const [count, setCount] = pp.state(0);
+    </script>
 </section>
-<script>
-    const [count, setCount] = pp.state(0);
-</script>
 ```
 That is the default structure for a PulsePoint-aware route page.
 Use `MainLayout::$title` and `MainLayout::$description` for page metadata, and keep a separate heading variable only when the visible heading text needs to differ.
-By contrast, **imported partials rendered with `ImportComponent::render(...)` follow a different rule**: the imported file must emit exactly **one root element**, and if it contains a `<script>`, that script must live **inside** that root element. Read `components.md` for that pattern.
+By contrast, **imported partials rendered with `ImportComponent::render(...)` keep the same single-root requirement but a different `pp-component` responsibility**: the imported file must emit exactly **one root element**, any component-local `<script>` must live **inside** that root element, and Prisma PHP injects `pp-component` on that imported root automatically. Read `components.md` for that pattern.
 ## Creating a page
@@ -167,7 +167,7 @@ use PP\MainLayout;
 ```
 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>`.
+If this root layout uses PulsePoint, keep the same file order: PHP first, then the document HTML, and keep any route-local `<script>` inside a single wrapper near the end of `<body>`.
 ## Creating a nested route
@@ -385,10 +385,10 @@ echo json_encode($users);
 - 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.
+- When `index.php` or `layout.php` uses PulsePoint, structure the file as PHP first, then one root HTML element, and keep the `<script>` inside that root as its last child.
 - `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.
 - Private folders help you colocate implementation files without making them routable.
-- Imported partials rendered through `ImportComponent` follow a different structural rule: one root element containing any component-local `<script>`.
+- Imported partials rendered through `ImportComponent` follow the same single-root rule but a different boundary rule: keep the component-local `<script>` inside that root and let Prisma PHP inject `pp-component` there.

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

@@ -114,7 +114,7 @@ For normal PulsePoint-aware route files, use:
 1. PHP
 2. one parent HTML element
-3. one `<script>` block after that parent element
+3. when PulsePoint is present, keep one `<script>` block as the last child inside that same root element
 Example:
@@ -127,14 +127,13 @@ MainLayout::$title = 'Dashboard';
 MainLayout::$description = 'View dashboard metrics and current activity.';
 ?>
-<section class="dashboard-page">
+<section pp-component="dashboard-page">
     <h1>Dashboard</h1>
     <p>Count: {count}</p>
+    <script>
+        const [count, setCount] = pp.state(0);
+    </script>
 </section>
-<script>
-    const [count, setCount] = pp.state(0);
-</script>
 ```
 That is the default route-file structure for a full-stack page.
@@ -144,18 +143,18 @@ For document metadata, set `MainLayout::$title` and `MainLayout::$description` i
 An imported partial rendered through `ImportComponent::render(...)` is **not** a normal route file.
-For imported partials, the file must emit exactly **one root element**, and if the partial contains a `<script>`, that script must live **inside** that root element.
+For imported partials, the file must emit exactly **one root element**, and if the partial contains a `<script>`, that script must live **inside** that root element. Prisma PHP injects `pp-component` for that imported boundary automatically.
 Example:
 ```php filename="src/app/inc/SearchBox.php"
 <?php
-$title = 'Search';
+// PHP Code
 ?>
-<div class="rounded-lg border p-4" pp-component="search-box">
-    <h2><?= htmlspecialchars($title) ?></h2>
+<div pp-component="search-box">
+    <h2>Search</h2>
     <input value="{query}" />
     <script>
         console.log('Search component ready');

package/dist/docs/pulsepoint.md CHANGED Viewed

@@ -2,30 +2,48 @@
 ## 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.
+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 `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.
+Do not assume React, Vue, Svelte, JSX, or older PulsePoint docs.
-## What the runtime actually does
+## Runtime shape
-PulsePoint is a browser-side component runtime. It renders HTML, binds state and events, and morphs the DOM in place.
+PulsePoint is a browser-side component runtime. It executes one component script per root, renders HTML from the component scope, morphs the DOM in place, binds native event handlers, restores focus, and runs hook effects.
 A component root is any element with `pp-component`.
+Important:
+- In the current source, `pp-component` behaves like an instance id, not a reusable component class name.
+- State, scope, template caching, parent tracking, and instance lookup are all keyed by that attribute.
+- Generate unique `pp-component` values per mounted instance. Reusing the same value for multiple live roots can replace or destroy the previous instance.
 ## Component roots and scripts
 - Each component root may contain one inline `<script>` block for component logic.
+- The runtime looks for that script inside the current root and ignores scripts inside nested component roots.
+- Plain `<script>` is not the component-script contract in the current TypeScript source.
 - 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.
+- Do not manually `return { ... }`. The runtime auto-exports supported top-level 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.
+- `children` is injected into props and contains the root's initial inner HTML.
+Bindings that are exported to the template:
+- Top-level function declarations.
+- Top-level identifier declarations such as `const title = ...`.
+- Top-level object destructuring identifiers such as `const { title, subtitle } = pp.props`.
+- Top-level array destructuring from `pp.state(...)`, such as `const [count, setCount] = pp.state(0)`.
+Bindings that should not be assumed:
+- Generic top-level array destructuring is not auto-exported unless it comes from `pp.state(...)`.
+- Nested declarations inside functions, conditions, loops, and callbacks are not auto-exported.
 Example:
 ```html
-<div pp-component="counter-card">
+<div pp-component="counter-card-1">
   <h2>{title}</h2>
   <p>Count: {count}</p>
   <button onclick="setCount(count + 1)">Increment</button>
@@ -33,7 +51,6 @@ Example:
   <script>
     const { title } = pp.props;
     const [count, setCount] = pp.state(0);
-    const doubled = count * 2;
     function reset() {
       setCount(0);
@@ -42,32 +59,104 @@ Example:
 </div>
 ```
-## Hooks exposed through `pp`
+## Hooks and runtime API
+Hooks exposed inside component scripts through `pp`:
 - `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.effect(callback, deps?)` runs after render and may return a cleanup function.
+- `pp.layoutEffect(callback, deps?)` runs synchronously after DOM mutation and may return a cleanup function.
 - `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.context(token)` resolves a provided context value from ancestor components.
+- `pp.provideContext(token, value)` provides a context value to descendant components.
 - `pp.portal(ref, target?)` portals a ref-managed element into a target.
 - `pp.props` exposes the current props.
+Runtime helpers exposed through the global `pp` utility object:
+- `pp.createContext(defaultValue)` creates a context token.
+- `pp.mount()` bootstraps the runtime.
+- `pp.redirect(url)` performs SPA-aware navigation when enabled.
+- `pp.fetchFunction(name, data?, optionsOrAbort?)` performs the runtime RPC/fetch bridge.
+- `pp.enablePerf()` enables render timing collection.
+- `pp.disablePerf()` disables render timing collection.
+- `pp.getPerfStats()` returns collected render timings.
+- `pp.resetPerfStats()` clears collected render timings.
 Notes:
 - `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.
+- `pp.effect` and `pp.layoutEffect` behave like cleanup-style hooks. Do not rely on returned promises being awaited.
+- `pp.mount()` should be called once. Do not manually instantiate `Component`.
 - Keep template-facing bindings at the top level so the AST-based exporter can see them.
+## Context
+Context is implemented in the current source. Do not document it as unsupported.
+How it works:
+- Create a token with `pp.createContext(defaultValue)`.
+- Provide a value from a component with `pp.provideContext(token, value)`.
+- Read it in a descendant component with `pp.context(token)`.
+- Resolution walks the component parent chain and falls back to `token.defaultValue` when no provider exists.
+- Descendant consumers are refreshed when a provider value changes or the provider is destroyed.
+Important:
+- The same token object must be shared between provider and consumer.
+- In this runtime, context is component-level, not directive-based. There is no `pp-context` attribute.
+- If components are isolated in separate script blocks, pass the token through props or store it in a shared outer scope.
+Example:
+```html
+<section pp-component="theme-provider-1">
+  <div pp-component="theme-label-1" theme-token="{ThemeContext}">
+    <p>{theme}</p>
+    <script>
+      const { themeToken } = pp.props;
+      const theme = pp.context(themeToken);
+    </script>
+  </div>
+  <script>
+    const ThemeContext = pp.createContext("light");
+    const [theme] = pp.state("dark");
+    pp.provideContext(ThemeContext, theme);
+  </script>
+</section>
+```
+## Props and nested components
+- Child component props are derived from DOM attributes.
+- Attribute names are converted from kebab-case to camelCase for the prop bag.
+- Pure prop expressions such as `title="{pageTitle}"` are evaluated in the parent scope.
+- Mixed strings such as `class="card {isActive ? 'active' : ''}"` are interpolated in the parent scope.
+- Empty attributes become boolean `true` props.
+Nested components:
+- Nested `pp-component` roots are treated as component boundaries during DOM reconciliation.
+- Nested roots with their own `<script>` are also masked during parent template compilation.
+- Scriptless nested component roots are bootstrapped, but they are not fully masked during parent template compilation in the current source. Avoid generating child-local interpolations inside a nested root unless that child has its own `<script>`.
 ## Template expressions and attributes
 - 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.
+- Arrays in template expressions are joined without commas.
+- `null`, `undefined`, and boolean expression results render as an empty string.
+- Boolean attributes are normalized for the supported attribute names implemented by the runtime.
 - 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.
+- Use plain `key` for keyed diffing. `pp-key` is not implemented.
 Example:
@@ -79,6 +168,7 @@ Example:
     class: "btn btn-primary",
     "aria-label": "save",
   };
   const isLoading = false;
 </script>
 ```
@@ -86,15 +176,16 @@ Example:
 ## Refs
 - 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.
+- Use `pp-ref="{registerRef(id)}"` when you want the compiled template to capture a dynamic ref expression.
 - `pp.ref(null)` is the normal way to create a ref object.
+- Callback refs and `{ current }` refs are both supported.
 - 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.
 Example:
 ```html
-<div pp-component="focus-box">
+<div pp-component="focus-box-1">
   <input pp-ref="nameInput" />
   <button onclick="nameInput.current?.focus()">Focus</button>
@@ -104,14 +195,15 @@ Example:
 </div>
 ```
-## Lists and loops
+## Lists and keyed diffing
 - 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.
+- Event handlers inside loops are rewritten so loop variables still resolve after rerender.
 - Use stable unique `key` values on repeated elements.
-- Duplicate keys can trigger warnings, so do not use random keys.
+- Duplicate keys trigger warnings and reduce diff quality.
 Example:
@@ -154,34 +246,30 @@ Example:
 - `pp-loading-transition` accepts JSON with `fadeIn` and `fadeOut` timing values.
 - `pp-reset-scroll="true"` resets scroll positions during navigation.
-The runtime also exposes navigation and bridge helpers through `pp`:
-- `pp.mount()`
-- `pp.redirect(url)`
-- `pp.fetchFunction(name, data?, optionsOrAbort?)`
-- `pp.enablePerf()`
-- `pp.disablePerf()`
-- `pp.getPerfStats()`
-- `pp.resetPerfStats()`
 Notes:
-- `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.
+- `pp.redirect()` uses SPA navigation when enabled and the URL is same-origin. Otherwise it falls back to normal navigation.
+- `pp.fetchFunction()` posts to the current route and supports aborting previous requests, upload progress, and streamed responses when available.
+- `pp.mount()` bootstraps every `[pp-component]` it finds, so AI-generated code should call it once and let the runtime manage nested components.
-## Plain HTML bundle usage
+## AI rules
-When the app is shipped as plain HTML plus a minified bundle:
+Use these rules when generating or editing PulsePoint code:
-- 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>` blocks in the HTML.
-- Do not assume access to the TypeScript source at runtime.
+- Use the current TypeScript source when it is available.
+- Generate unique `pp-component` values per live instance.
+- Use only `<script>` for component logic.
+- Keep template-facing variables at top level.
+- Use `pp.createContext`, `pp.context`, and `pp.provideContext` for context. Do not invent `pp-context`.
+- Keep `pp-for` on `<template>` and use plain `key`.
+- Use native `on*` attributes, not framework-specific event syntax.
+- Use refs and portals only through the implemented `pp` APIs.
+- Avoid generating internal runtime attributes.
+- Avoid scriptless nested components when the child template contains its own bindings.
 ## What to avoid
-Do not generate these unless the current source explicitly supports them:
+Do not generate these unless the current source explicitly adds support:
 - `pp-context`
 - `pp-key`
@@ -192,20 +280,17 @@ Do not generate these unless the current source explicitly supports them:
 - `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
+- React, Vue, Svelte, or JSX-only patterns that are not implemented here
 - made-up hooks, directives, or globals not present in the current TypeScript source
-## AI checklist
+## Review notes
-When working on PulsePoint code, follow this order:
+These are current runtime caveats that matter for authors and AI tools:
-- 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.
+- `pp-component` is currently used as the registry key for instances, state, parent tracking, and templates. Treat it as unique per mounted root.
+- Nested roots without their own `<script>` are not fully isolated during parent template compilation.
+- `pp.mount()` boots every root in the document. Call it once and avoid manual component construction.
+- `pp.effect` and `pp.layoutEffect` are cleanup-style hooks. Their callbacks are not promise-aware.
 ## Final reminder

package/package.json CHANGED Viewed

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