caspian-utils 0.0.18 → 0.0.20

package/dist/docs/components.md

@@ -1,6 +1,6 @@
 ---
 title: Components
-description: Use this page when the task mentions `@component`, reusable UI, component imports, same-name `.html` templates, or where shared components belong in a Caspian project.
+description: Use this page when the task mentions `@component`, reusable UI, HTML-first `x-*` component tags, component imports, same-name `.html` templates, `merge_classes(...)`, `twMerge(...)`, or where shared components belong in a Caspian project.
 related:
   title: Related docs
   description: Use the structure guide for file placement, the routing guide for route templates, the PulsePoint guide for browser-side scripts, and the data guide for component-owned RPC flows.
@@ -12,9 +12,11 @@ related:
     - /docs/index
 ---
 
-Components in Caspian are Python functions decorated with `@component`.
+Components in Caspian are implemented as Python functions decorated with `@component`.
 
-Import them into a template with an `@import` comment, then render them with JSX-style tags such as `<MyComponent />` or `<MyComponent>...</MyComponent>`.
+In authored HTML, import them with an `@import` comment and render them with HTML-first kebab-cased `x-*` tags such as `<x-my-component />` or `<x-my-component>...</x-my-component>`.
+
+Treat that `x-*` form as the current Caspian component contract for authored templates.
 
 Component tooling scans Python files under the paths listed in `caspian.config.json`. When `componentScanDirs` includes `src/`, `src/components/` is the clean default location for reusable UI, even though any scanned path can work.
 
@@ -29,7 +31,7 @@ As the app grows, treat `src/components/` as the default home for reusable appli
 
 ## Basic Component
 
-This is the simplest pattern: accept props, merge classes or attributes, and return HTML.
+This is the simplest pattern: accept props, assemble the final class value, and return HTML.
 
 ```python
 from casp.component_decorator import component
@@ -51,7 +53,44 @@ Notes:
 
 - `children` receives the inner content passed between opening and closing tags.
 - `**props` lets the component accept additional HTML attributes such as `id`, `data-*`, and `aria-*`.
-- The runtime normalizes `class`, `className`, and `class_name` into a merged `class` value before the component is called.
+- The runtime normalizes `class`, `className`, and `class_name` into one `class` value before the component is called.
+- Pass the `merge_classes(...)` result straight into `get_attributes(...)` or the rendered `class` attribute; do not wrap it in another helper.
+
+## Tailwind Merge Contract
+
+When `caspian.config.json` has `tailwindcss: true`, Caspian uses a frontend-first Tailwind merge contract.
+
+- In Python components, use `merge_classes(...)` to assemble class defaults plus incoming class props.
+- `merge_classes(...)` emits a frontend-ready `{twMerge(...)}` expression instead of doing Python-side Tailwind conflict resolution.
+- In authored PulsePoint markup and scripts, use global `twMerge(...)` directly for attribute expressions and script-local derived values.
+
+Python example:
+
+```python
+from casp.component_decorator import component
+from casp.html_attrs import get_attributes, merge_classes
+
+@component
+def IconButton(**props) -> str:
+    incoming_class = props.pop("class", "")
+    final_class = merge_classes("size-4 rounded-md", incoming_class)
+
+    attributes = get_attributes({
+        "class": final_class,
+    }, props)
+
+    return f'<button {attributes}></button>'
+```
+
+Authored PulsePoint examples:
+
+```html
+<p class="{twMerge(baseClass, inputClass)}">Merged badge preview</p>
+
+<script>
+  const merged = twMerge(baseClass, inputClass);
+</script>
+```
 
 ## Import And Use Components
 
@@ -60,17 +99,17 @@ Place component imports at the top of the HTML template, above the authored root
 ```html
 <!-- @import Container from "../components" -->
 
-<Container class="py-10">
+<x-container class="py-10">
   <h1>Dashboard</h1>
-</Container>
+</x-container>
 ```
 
-The import comment is the bridge between the Python component file and the JSX-style tag.
+The import comment is the bridge between the Python component export and the `x-*` tag you author in HTML.
 
 Treat `<!-- @import ... -->` as a file-level directive, not as rendered markup. It does not count as the template root, and it should not be nested inside the root wrapper element.
 
 - `<!-- @import Container from "../components" -->` resolves `Container.py` from that folder.
-- The component function name should match the tag name you render, such as `Container` for `<Container />`.
+- The exported component name maps to the tag you render by kebab-casing it and prefixing `x-`, such as `Container` for `<x-container />` or `CommandDialog` for `<x-command-dialog />`.
 - Grouped imports and aliases are also supported, for example `<!-- @import { Button, Card as UserCard } from "../components/ui" -->`.
 - If one Python file exports several `@component` functions, point `from` at that exact file instead of assuming one file per tag.
 - In that case, prefer one grouped import so every rendered tag resolves back to the same Python module.
@@ -81,9 +120,9 @@ Good:
 <!-- @import { Button, Input, Label } from "../../../lib/maddex" -->
 
 <section class="auth-panel auth-panel-compact fade-up">
-  <Label>Email</Label>
-  <Input type="email" />
-  <Button>Continue</Button>
+  <x-label>Email</x-label>
+  <x-input type="email" />
+  <x-button>Continue</x-button>
 </section>
 ```
 
@@ -106,17 +145,17 @@ If `Breadcrumb.py` defines `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `Br
 <!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "../maddex/Breadcrumb.py" -->
 
 <div class="dashboard-topbar">
-  <Breadcrumb class="dashboard-breadcrumbs" aria-label="Dashboard breadcrumbs">
-    <BreadcrumbList class="dashboard-breadcrumbs__list">
-      <BreadcrumbItem class="dashboard-breadcrumbs__item">
-        <BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink>
-      </BreadcrumbItem>
-      <BreadcrumbSeparator class="dashboard-breadcrumbs__separator" />
-      <BreadcrumbItem class="dashboard-breadcrumbs__item">
-        <BreadcrumbPage class="dashboard-breadcrumbs__page">Reports</BreadcrumbPage>
-      </BreadcrumbItem>
-    </BreadcrumbList>
-  </Breadcrumb>
+  <x-breadcrumb class="dashboard-breadcrumbs" aria-label="Dashboard breadcrumbs">
+    <x-breadcrumb-list class="dashboard-breadcrumbs__list">
+      <x-breadcrumb-item class="dashboard-breadcrumbs__item">
+        <x-breadcrumb-link href="/dashboard">Dashboard</x-breadcrumb-link>
+      </x-breadcrumb-item>
+      <x-breadcrumb-separator class="dashboard-breadcrumbs__separator" />
+      <x-breadcrumb-item class="dashboard-breadcrumbs__item">
+        <x-breadcrumb-page class="dashboard-breadcrumbs__page">Reports</x-breadcrumb-page>
+      </x-breadcrumb-item>
+    </x-breadcrumb-list>
+  </x-breadcrumb>
 </div>
 ```
 
@@ -317,7 +356,7 @@ Keep synchronous components as the default. Switch to `async def` only when the
 
 - Put reusable components in `src/components/` and keep route files in `src/app/`.
 - If the component includes PulsePoint behavior, prefer a thin Python wrapper plus a same-name `.html` template.
-- Keep the component file name, exported function name, and tag name aligned, such as `Button.py`, `def Button(...)`, and `<Button />`.
+- Keep the component file name, exported function name, and authored tag aligned, such as `Button.py`, `def Button(...)`, and `<x-button />`.
 - Accept `children` or `**props` when the component should support nested content.
 - Keep page-level data loading in `page()` when the data is not intrinsic to the component itself.
 - If you add `@rpc()` functions inside a component file, keep their names globally unique because component RPCs are not route-scoped.

package/dist/docs/index.md

@@ -26,6 +26,7 @@ Before making feature, tooling, or file-placement decisions in a Caspian project
 When generating or editing a Caspian app, treat these as the default choices unless the task explicitly requires something else:
 
 - Use PulsePoint for reactive frontend behavior.
+- When `caspian.config.json` has `tailwindcss: true`, use Python `merge_classes(...)` plus browser `twMerge(...)` as the only supported Tailwind class-merging path.
 - Use `@rpc()` plus `pp.rpc()` for browser-triggered reads, writes, streaming, and uploads.
 - Use `Validate` and `Rule` from `casp.validate` for server-side input validation and sanitization.
 
@@ -42,8 +43,8 @@ The packaged Caspian docs referenced by this index live here:
 - `mcp.md` - MCP-specific layout, launch flow, and AI routing rules for projects where `caspian.config.json` enables MCP
 - `database.md` - Prisma schema, migration, seed, and client-generation workflow for projects where `caspian.config.json` enables Prisma, plus Python-side helper caveats
 - `auth.md` - Session-backed authentication with `casp.auth`, centralized `auth_config.py`, public-vs-private route mode guidance, RPC-first signout guidance, RBAC, and OAuth provider helpers
-- `components.md` - Create reusable Python components, template-backed UI, JSX-style imports, and the single-parent root rule for component HTML files
-- `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, state, effects, directives, and client-side behaviors
+- `components.md` - Create reusable Python components, template-backed UI, HTML-first `x-*` component tags, the single-parent root rule for component HTML files, and the Python-side `merge_classes(...)` contract when Tailwind CSS is enabled
+- `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, state, effects, directives, client-side behaviors, and direct browser `twMerge(...)` usage when Tailwind CSS is enabled
 - `fetch-data.md` - Initial server-side data loading and browser-triggered RPC flows with `pp.rpc()`, streaming, uploads, and auth-aware actions
 - `file-uploads.md` - Route-local file uploads and file-manager flows with `@rpc()`, `pp.rpc()`, Prisma metadata, public asset storage, and BrowserSync ignore rules
 - `state.md` - Request-scoped server state with `StateManager`, session-backed JSON persistence, and listener callbacks for transient flows

package/dist/docs/project-structure.md

@@ -119,9 +119,9 @@ Use this folder for reusable UI components that should be imported into route te
 
 As the app grows, default to `src/components/` for application-level UI that will be shared across routes or features. Keep page-only markup close to the route in `src/app/`, but move shared cards, forms, shells, navigation, and other reusable visual building blocks into `src/components/`.
 
-The common Caspian pattern is a Python file such as `Button.py` with `@component`, optionally paired with a same-name HTML file such as `Button.html` when the component has richer markup or PulsePoint behavior.
+The common Caspian pattern is a Python file such as `Button.py` with `@component`, optionally paired with a same-name HTML file such as `Button.html` when the component has richer markup or PulsePoint behavior. In authored HTML, that component is consumed as `<x-button />`.
 
-One Python file can also export multiple related `@component` functions. When that happens, import those tags from that exact file path in HTML, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`, instead of assuming each tag has its own sibling `.py` file.
+One Python file can also export multiple related `@component` functions. When that happens, import those tags from that exact file path in HTML, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`, and render them as `<x-breadcrumb />`, `<x-breadcrumb-item />`, and `<x-breadcrumb-list />` instead of assuming each tag has its own sibling `.py` file.
 
 For component HTML files, follow the same one-parent rule as route HTML files: one top-level lowercase HTML element only, with no sibling roots and no top-level script sitting outside that root.
 
@@ -243,7 +243,7 @@ If a route renders UI and needs no backend behavior, this file alone is sufficie
 
 Treat import comments as top-of-file directives that belong above the route's single authored root element.
 
-Use `components.md` when the task involves authoring reusable `<MyComponent />` tags backed by Python files.
+Use `components.md` when the task involves authoring reusable `<x-my-component />` tags backed by Python files.
 
 ### `src/app/globals.css`
 
@@ -278,7 +278,7 @@ If an AI agent is deciding where to make changes, use these rules first.
 - As the app grows, keep route-owned code in `src/app/`, reusable rendered UI in `src/components/`, and reusable non-UI support code in `src/lib/`.
 - Read [file-uploads.md](./file-uploads.md) when the task involves upload widgets, media libraries, or file-manager flows.
 - Check [routing.md](./routing.md) when you need URL segment rules, layout nesting behavior, or dynamic route conventions.
-- Put reusable component files in `src/components/` and check [components.md](./components.md) for `@component`, `render_html(__file__)`, import comments, and single-root template rules.
+- Put reusable component files in `src/components/` and check [components.md](./components.md) for `@component`, `render_html(__file__)`, `x-*` component tags, import comments, and single-root template rules.
 - When deciding between `src/components/` and `src/lib/`, use `src/components/` for anything rendered as reusable UI and `src/lib/` for helpers, services, validators, adapters, and shared business logic.
 - Use [mcp.md](./mcp.md) only when `caspian.config.json` enables MCP and the task involves FastMCP tool definitions, nested config discovery, or local MCP commands.
 - Keep `<!-- @import ... -->` comments above the single authored root element in route, layout, and component HTML files.

package/dist/docs/pulsepoint.md

@@ -16,9 +16,9 @@ related:
 
 This file documents the PulsePoint contract for the shipped Caspian browser runtime. Treat it as the AI-facing source of truth when generating or reviewing interactive Caspian UI.
 
-If a task involves `pp.state`, `pp.effect`, `pp.layoutEffect`, `pp-ref`, `pp-style`, `pp-spread`, `pp-for`, context, portals, SPA navigation, or component boundary behavior, read this page first and keep generated code aligned with the runtime implemented in this repo.
+If a task involves `pp.state`, `pp.effect`, `pp.layoutEffect`, `pp-ref`, `pp-style`, `pp-spread`, `pp-for`, context, portals, SPA navigation, or component boundary behavior, read this page first and keep generated code aligned with the current Caspian runtime.
 
-Use `components.md` for authoring Python `@component` files and same-name HTML templates. Use this page for the browser-side PulsePoint contract, the authoring rules that feed it, and the React-style mental model used by the shipped runtime.
+Use `components.md` for authoring Python `@component` files, same-name HTML templates, and HTML-first `x-*` component tags. Use this page for the browser-side PulsePoint contract, the authoring rules that feed it, and the React-style mental model used by the shipped runtime.
 
 PulsePoint is the default reactive frontend layer for Caspian. In the current runtime it follows a React-like component pattern, but it is HTML-first rather than JSX-first.
 
@@ -36,6 +36,7 @@ Important current facts:
 
 - `public/js/pp-reactive-v2.js` exposes the global `pp` runtime and auto-mounts on DOM ready.
 - `main.py` renders the final HTML, runs `transform_components(...)`, then runs `transform_scripts(...)` before returning the response.
+- Authored route and component templates compose reusable server components as HTML-first `x-*` tags before the browser runtime mounts.
 
 If docs, generated examples, or older notes disagree with `public/js/pp-reactive-v2.js` plus `main.py`, follow the code that actually runs.
 
@@ -51,7 +52,7 @@ When a Caspian page needs reactive browser behavior, use PulsePoint.
 
 ## Authoring Model
 
-PulsePoint authoring in this repo is split into two layers:
+PulsePoint authoring is split into two layers:
 
 - The authored layer: route, layout, and component templates under `src/` with plain HTML plus a plain `<script>`.
 - The runtime layer: the browser sees `pp-component` roots and `script[type="text/pp"]` after Caspian transforms the HTML.

package/dist/docs/routing.md

@@ -89,7 +89,7 @@ Use `index.html` for the route template. This is the route's view layer.
 
 If a route renders visible page content, that content belongs here even when the route also has an `index.py` companion.
 
-Route templates can import reusable Python components with `<!-- @import ... -->` comments and render them with JSX-style tags such as `<Button />`. Use [components.md](./components.md) for the component authoring rules.
+Route templates can import reusable Python components with `<!-- @import ... -->` comments and render them with HTML-first `x-*` tags such as `<x-button />`. Use [components.md](./components.md) for the component authoring rules.
 
 Place those import comments at the top of the file, above the authored root element. They are file-level directives, not children of the route root.
 
@@ -130,7 +130,7 @@ Also bad:
 ```html
 <section class="dashboard-shell">
   <!-- @import StatsCard from "../components" -->
-  <StatsCard title="Users" value="42" />
+  <x-stats-card title="Users" value="42" />
 </section>
 ```
 
@@ -140,7 +140,7 @@ Example authored route template:
 <!-- @import StatsCard from "../components" -->
 
 <section class="dashboard-shell">
-  <StatsCard title="Users" value="42" />
+  <x-stats-card title="Users" value="42" />
 
   <script>
     const [filter, setFilter] = pp.state("all");

package/package.json

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