prisma-php 0.0.8 → 0.0.9

package/dist/docs/pulsepoint.md

@@ -2,31 +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.
-- Keep that `<script>` inside the same `pp-component` root. Do not leave it as a sibling after the root element.
+- 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>
@@ -34,7 +51,6 @@ Example:
   <script>
     const { title } = pp.props;
     const [count, setCount] = pp.state(0);
-    const doubled = count * 2;
 
     function reset() {
       setCount(0);
@@ -43,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:
 
@@ -80,6 +168,7 @@ Example:
     class: "btn btn-primary",
     "aria-label": "save",
   };
+
   const isLoading = false;
 </script>
 ```
@@ -87,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>
 
@@ -105,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:
 
@@ -155,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,21 +279,18 @@ Do not generate these unless the current source explicitly supports them:
 - `pp-dynamic-script`
 - `pp-dynamic-meta`
 - `pp-dynamic-link`
-- component logic `<script>` blocks outside a `pp-component` root
-- React, Vue, Svelte, or JSX-style component patterns that are not implemented here
+- plain `<script>` for component logic inside a component root
+- 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

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