caspian-utils 0.1.11 → 0.1.13

package/dist/docs/commands.md

@@ -103,14 +103,17 @@ Do not use `npm run build` as the default validation step for routine route, fea
 ```bash
 npx prisma migrate dev
 
-# If the change requires refreshed seed data:
-npx prisma generate
-npx prisma db seed
-
-npx ppy generate
-```
-
-Use when `prisma/schema.prisma` changes and you need migrations, seed flow, and the generated Python ORM layer to stay aligned.
+# If the change requires refreshed seed data:
+npx prisma generate
+# Destructive-data warning: ask the user for explicit approval before running this.
+npx prisma db seed
+
+npx ppy generate
+```
+
+Use when `prisma/schema.prisma` changes and you need migrations, seed flow, and the generated Python ORM layer to stay aligned.
+
+`npx prisma db seed` is a delicate operation because the configured seed script may clean tables or replace existing rows before inserting seed data. Before running it, an AI agent must say the exact command it plans to run, warn that it can delete or overwrite database data, confirm the active datasource when practical, and wait for explicit user approval.
 
 ## 2. Script Guardrails
 
@@ -595,17 +598,18 @@ The create and update commands above are not the whole maintenance story for a P
 ```bash
 npx prisma migrate dev
 
-# Only when seed flow or prisma/seed.ts depends on the new schema:
-npx prisma generate
-npx prisma db seed
-
-npx ppy generate
-```
+# Only when seed flow or prisma/seed.ts depends on the new schema:
+npx prisma generate
+# Destructive-data warning: ask the user for explicit approval before running this.
+npx prisma db seed
+
+npx ppy generate
+```
 
 Use this order:
 
 1. Run `npx prisma migrate dev` first so migrations and the development database stay aligned.
-2. If `prisma/seed.ts` or seed data depends on the new schema, run `npx prisma generate` and then `npx prisma db seed`.
+2. If `prisma/seed.ts` or seed data depends on the new schema, run `npx prisma generate`, then request explicit user approval before running `npx prisma db seed` because the seed script may delete or overwrite database data.
 3. Run `npx ppy generate` last so the generated Python ORM layer matches the updated Prisma schema.
 
 Do not manually create or edit these generated files:
@@ -678,7 +682,7 @@ If an AI agent is deciding which command flow to use, apply these rules first.
 - Treat `--tailwindcss` and `--typescript` as frontend-oriented flags. They are not meaningful in normal backend-only scaffolds.
 - Treat starter kit defaults as a base layer that can be overridden by explicit flags.
 - Read `caspian.config.json` before running update commands.
-- When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first, then any required seed refresh, then `npx ppy generate`.
+- When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first, then any required seed refresh, then `npx ppy generate`. Before running `npx prisma db seed`, warn the user that it can delete or overwrite data and wait for explicit approval.
 - Never hand-edit generated Python ORM files under `src/lib/prisma/` or `settings/prisma-schema.json`.
 - Read [database.md](./database.md) before generating Prisma schema, migration, seed, or ORM guidance.
 - Read [routing.md](./routing.md) before generating or modifying route folders under `src/app/`.

package/dist/docs/database.md

@@ -22,16 +22,30 @@ Treat `caspian.config.json` as the single source of truth for whether Prisma is
 
 ## Overview
 
-The standard Prisma flow in Caspian is:
-
-1. Define models in `prisma/schema.prisma`.
-2. Configure `DATABASE_URL` in `.env`.
-3. Run `npx prisma migrate dev` after schema changes so the development database and migration history stay aligned.
-4. If the change requires seed data, run `npx prisma generate` and then `npx prisma db seed`.
-5. Run `npx ppy generate` so the Python ORM classes stay aligned with the updated schema.
-6. Reuse the shared Python database layer in `src/lib/prisma/` when Python route or RPC code needs database access, and never hand-edit generated ORM classes.
-
+The standard Prisma flow in Caspian is:
+
+1. Define models in `prisma/schema.prisma`.
+2. Configure `DATABASE_URL` in `.env`.
+3. Run `npx prisma migrate dev` after schema changes so the development database and migration history stay aligned.
+4. If the change requires seed data, run `npx prisma generate`, then request explicit user approval before running `npx prisma db seed`.
+5. Run `npx ppy generate` so the Python ORM classes stay aligned with the updated schema.
+6. Reuse the shared Python database layer in `src/lib/prisma/` when Python route or RPC code needs database access, and never hand-edit generated ORM classes.
+
 Use this workflow instead of writing raw SQL first. For normal CRUD and relation work, stay on the generated Prisma API. Drop to raw SQL only through Prisma when a query cannot be expressed clearly with the generated client, and assume that raw SQL requires extra review for cross-database portability.
+
+## Seed Command Safety
+
+Treat `npx prisma db seed` as a destructive data operation, not as a routine regeneration command. A project's `prisma/seed.ts` may delete existing rows, reset lookup tables, replace users, or otherwise rewrite the current datasource before inserting seed data. If `DATABASE_URL` points at a shared, staging, or production database, running the seed command can delete production information.
+
+Before any AI agent runs `npx prisma db seed`, it must:
+
+1. Read `prisma.config.ts` and `prisma/seed.ts` to understand what the seed command will execute.
+2. State the exact command it intends to run: `npx prisma db seed`.
+3. Warn the user clearly that the command can delete or overwrite database data.
+4. Confirm the active datasource or `DATABASE_URL` when practical, without exposing secrets.
+5. Wait for explicit user approval before executing the command.
+
+Do not run `npx prisma db seed` merely because it appears in the standard workflow. Ask first, and only continue after the user has approved that specific seed operation.
 
 ## Environment Setup
 
@@ -107,7 +121,7 @@ model Post {
 After changing the schema, use this order:
 
 1. Run `npx prisma migrate dev`.
-2. If seed data or the seed script needs the new schema, run `npx prisma generate` and then `npx prisma db seed`.
+2. If seed data or the seed script needs the new schema, run `npx prisma generate`, then request explicit user approval before running `npx prisma db seed`.
 3. Run `npx ppy generate` to refresh the generated Python ORM classes.
 
 Do not hand-edit generated Prisma or Python ORM output. Treat `prisma/schema.prisma` as the source of truth and regenerate from it.
@@ -117,8 +131,8 @@ Do not hand-edit generated Prisma or Python ORM output. Treat `prisma/schema.pri
 Use these commands for the normal Prisma lifecycle in Caspian:
 
 - `npx prisma migrate dev` creates and applies a development migration. This is the first command to run after changing `prisma/schema.prisma`.
-- `npx prisma generate` compiles `schema.prisma` into the generated Node Prisma client. Run it before `npx prisma db seed` when the updated seed flow depends on the new schema.
-- `npx prisma db seed` runs the configured seeding script.
+- `npx prisma generate` compiles `schema.prisma` into the generated Node Prisma client. Run it before `npx prisma db seed` when the updated seed flow depends on the new schema.
+- `npx prisma db seed` runs the configured seeding script. This may delete or overwrite existing database data; an AI agent must warn the user and receive explicit approval before executing it.
 - `npx ppy generate` regenerates the Python ORM classes used by the app. Use this after every schema change.
 - `npx prisma migrate deploy` applies pending migrations in deployment environments.
 - `npx prisma db push` syncs schema changes without creating a migration file, which is useful for prototyping.
@@ -126,7 +140,7 @@ Use these commands for the normal Prisma lifecycle in Caspian:
 
 Default rule:
 
-- When `prisma/schema.prisma` changes, use this order: `npx prisma migrate dev`; if seeding is involved, run `npx prisma generate` and `npx prisma db seed`; then run `npx ppy generate`.
+- When `prisma/schema.prisma` changes, use this order: `npx prisma migrate dev`; if seeding is involved, run `npx prisma generate`, ask for explicit approval before `npx prisma db seed`, then run `npx ppy generate`.
 - Never hand-edit generated Prisma or Python ORM classes, and never replace `npx ppy generate` with a manual class update.
 - Use migrations for tracked application changes.
 - Use `db push` only when you intentionally want a faster, migration-free prototype loop.
@@ -359,7 +373,7 @@ If an AI agent is working on a Caspian app with Prisma enabled, apply these rule
 - Treat Prisma as the default ORM and persistence layer.
 - Read `prisma/schema.prisma` before proposing model, relation, or field changes.
 - When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first.
-- If the schema change requires seed data, run `npx prisma generate` and then `npx prisma db seed`.
+- If the schema change requires seed data, run `npx prisma generate`, then request explicit user approval before running `npx prisma db seed`.
 - Run `npx ppy generate` after schema changes to refresh the Python ORM classes.
 - Never hand-edit generated Prisma or Python ORM classes.
 - Read `prisma.config.ts` and `prisma/seed.ts` when you need the current project's Prisma tooling examples.

package/dist/docs/pulsepoint-runtime-map.md

@@ -47,6 +47,7 @@ If an inspected browser DOM disagrees with authored template source, remember th
 | SPA navigation | `body[pp-spa="true"]`, links | `pp-reactive-v2.js`, `main.py` | same-origin eligible links intercept; root-layout mismatches hard reload |
 | Scroll restoration | `pp-reset-scroll="true"` | `pp-reactive-v2.js` | push navigation resets window; mark only content panes that should reset |
 | Tailwind merge | `{twMerge(...)}`, Python `merge_classes(...)` | `html_attrs.py`, `pp-reactive-v2.js` | Python emits frontend-ready expressions when Tailwind is enabled |
+| Markup deferral | `<template pp-component>` / `<template pp-owner>` wrappers | render pipeline (`main.py`), `pp-reactive-v2.js` (`materializeTemplateComponentBoundaries`) | top-level roots ship inside an inert `<template>`; runtime materializes them on mount and SPA navigation before scanning. Browser never validates `<template>` contents, so `{...}` is safe in any attribute/position (SVG geometry, `src`/`href`, form `value`/date, table/select text) — no per-tag workarounds. See [pulsepoint.md](./pulsepoint.md) "Component markup is deferred inside an inert `<template>`" |
 
 ## AI Decision Rules
 

package/dist/docs/pulsepoint.md

@@ -346,12 +346,12 @@ Important:
 - The script lookup walks the current root and skips nested `pp-component` boundaries, so a parent does not consume a child component's script.
 - If multiple matching runtime scripts exist in the same root, the first matching owned script wins. Generate one script per root.
 - Authored route, layout, and component templates still need one top-level parent node so Caspian can inject the component boundary correctly after component expansion.
-- A scriptless component root still mounts and can receive props, refs, events, and nested children, but it does not create local bindings from those props on its own.
+- A scriptless component root still mounts and can receive props, refs, events, and nested children, but it does not create local bindings from those props on its own.
 - Component scripts are plain JavaScript executed with `new Function(...)`. Do not use `import`, `export`, or top-level `await` inside them.
 - The runtime auto-returns supported top-level bindings from the script. Do not rely on manual `return { ... }` objects.
-- `pp.props` contains the current prop bag for the component.
-- `pp.props.children` contains the root's initial inner HTML before the owned script is removed from the render template.
-- Props are not auto-injected as standalone top-level template or handler variables. Read them through `pp.props` or explicitly destructure them in the component script.
+- `pp.props` contains the current prop bag for the component.
+- `pp.props.children` contains the root's initial inner HTML before the owned script is removed from the render template.
+- Props are not auto-injected as standalone top-level template or handler variables. Read them through `pp.props` or explicitly destructure them in the component script.
 
 Bindings exported to the template:
 
@@ -570,13 +570,13 @@ When a child component needs the same token object, pass it from the provider sc
 
 - Child component props are derived from DOM attributes.
 - Attribute names are converted from kebab-case to camelCase for the prop bag.
-- Native `on*` attributes and `pp-component` are not included in props.
-- Empty attributes become boolean `true` props.
-- 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.
-- Non-expression attribute values are passed through as strings.
-- `children` is injected into props using the root's initial inner HTML.
-- Inside the child component, those values should be accessed through `pp.props` or a top-level destructure such as `const { title } = pp.props`; they are not implicitly available as bare identifiers.
+- Native `on*` attributes and `pp-component` are not included in props.
+- Empty attributes become boolean `true` props.
+- 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.
+- Non-expression attribute values are passed through as strings.
+- `children` is injected into props using the root's initial inner HTML.
+- Inside the child component, those values should be accessed through `pp.props` or a top-level destructure such as `const { title } = pp.props`; they are not implicitly available as bare identifiers.
 
 Nested components:
 
@@ -621,6 +621,14 @@ Example:
 </div>
 ```
 
+### Component markup is deferred inside an inert `<template>`
+
+The render pipeline wraps each top-level `pp-component` root in an inert `<template pp-component="…">`, and the runtime materializes it back into live DOM on `mount()` (and on every SPA navigation) before it scans for roots. The browser never parses, validates, or fetches the contents of a `<template>`, so raw `{...}` placeholders never reach live DOM at first paint.
+
+- Because of this, `{...}` is safe in **any** attribute or position — including slots the browser would otherwise validate eagerly: SVG geometry (`d`, `viewBox`, `points`, `transform`), URL attributes (`src`, `srcset`, `href`, `poster`), form `value` on `date`/`number`/`color` inputs, and text placed directly inside `<table>` or `<select>`.
+- Do not add per-tag workarounds to dodge first-paint validation (static-path `hidden` toggles instead of binding `d`, `data-*` URL holders, `hidden`-gated `<img src>`, or an SSR-resolved initial value). The deferral removes the whole class at once.
+- `pp-style` and the `<input>`/`<select>`/`checked`/`defaultvalue`/`<textarea>` value rewrites still apply — but for different reasons that deferral does not replace: authoring-source tooling (`style="{...}"` breaks HTML/CSS linters) and attribute-vs-property correctness for controlled form fields.
+
 ## Refs
 
 - Refs are for imperative element access. Do not use `pp-ref` as the default way to read normal form input values on submit; prefer the form's `onsubmit` event plus `Object.fromEntries(new FormData(event.currentTarget).entries())`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caspian-utils",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {