caspian-utils 0.0.19 → 0.0.21

package/dist/docs/components.md

@@ -1,6 +1,6 @@
 ---
 title: Components
-description: Use this page when the task mentions `@component`, reusable UI, HTML-first `x-*` component tags, 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.
@@ -31,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
@@ -53,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
 

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, HTML-first `x-*` component tags, 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/metadata.md

@@ -176,6 +176,7 @@ Use stable, publicly reachable image paths for social cards so crawlers can fetc
 Keep visual layout data and SEO metadata separate.
 
 - Values returned from `layout()` are exposed as `[[ layout.* ]]`.
+- The second dict returned from `page()` as `(page_html, layout_props_dict)` is also exposed to wrapping layouts as `[[ layout.* ]]`.
 - SEO values are exposed as `[[ metadata.* ]]`.
 - Do not return `title` or `description` from `layout()` expecting SEO changes.
 - The layout engine explicitly strips `title` and `description` from layout props to avoid mixing visual props with metadata.
@@ -195,6 +196,7 @@ If an AI agent is deciding where to put SEO fields, apply these rules first.
 - Prefer module-level `metadata = Metadata(...)` for static routes.
 - Instantiate `Metadata(...)` inside `page()` when metadata depends on params, fetched records, or generated content.
 - Put shared defaults in `layout.py` and let leaf pages override only what they need.
+- If a single route only needs to tweak a wrapping layout, return `(render_page(__file__, ...), {"dashboard_body_class": ...})` from `page()` instead of moving that prop into metadata.
 - Use `extra` for Open Graph and Twitter card tags.
 - Access `extra` values in templates with bracket syntax such as `metadata['og:image']`.
 - Keep `layout()` return data in `[[ layout.* ]]` and keep SEO fields in `Metadata(...)`.

package/dist/docs/routing.md

@@ -186,6 +186,37 @@ async def page():
 
 Use this pattern when the route needs to fetch data, compute metadata, or do other non-blocking server work before rendering the sibling `index.html`.
 
+`page()` may also return a 2-item tuple: `(page_html, layout_props_dict)`.
+
+- The first item is the rendered page HTML, usually `render_page(__file__, page_context)`.
+- The second item must be a dict. Its keys are merged into the wrapping layout context and become available to parent layouts as `[[ layout.* ]]`.
+
+Use that tuple form when one route needs to influence a wrapper without turning that value into a section-wide default. A common example is a dashboard page that needs to lock the root body with `overflow-hidden` while the rest of the app keeps normal scrolling.
+
+Example root layout:
+
+```html
+<body class="[[ layout.dashboard_body_class | default('') ]]">
+  [[ children | safe ]]
+</body>
+```
+
+Example route:
+
+```python
+from casp.layout import render_page
+
+async def page():
+  return (
+    render_page(__file__),
+    {"dashboard_body_class": "w-screen h-screen overflow-hidden"},
+  )
+```
+
+The key name is arbitrary, but it must match exactly between the dict returned from `page()` and the `[[ layout.some_key ]]` lookup in `layout.html`.
+
+Use distinct names for those layout props. In the current router, the second dict is merged into the full layout context after path params and `request`, so a key such as `slug` or `request` can shadow an existing value.
+
 When a route owns a file manager or upload UI, keep the owning upload and delete `@rpc()` actions in that same `index.py` and move reusable filesystem or Prisma helpers into `src/lib/`. Do not move ordinary upload behavior into `main.py`. See [file-uploads.md](./file-uploads.md).
 
 For static and dynamic metadata rules, inheritance order, and social card fields, see [metadata.md](./metadata.md).
@@ -289,12 +320,47 @@ def layout(context_data):
 
     return {
         "user": user,
+    "dashboard_body_class": "w-screen h-screen overflow-hidden",
         "theme": "dark",
     }
 ```
 
 `context_data` includes URL parameters such as dynamic route values.
 
+In the common case, return a dict and let the sibling `layout.html` read those values through `[[ layout.* ]]`.
+
+`layout()` currently supports these result shapes:
+
+- `dict`: load the sibling `layout.html` and expose the dict as `[[ layout.* ]]`
+- `str`: use that string as the layout content
+- `(layout_html, props_dict)`: use the first item as the layout content and expose the second dict as `[[ layout.* ]]`
+- `None`: fall back to the sibling `layout.html` with no extra layout props
+
+If you intentionally want to render `layout.html` immediately with direct local variables instead of the `layout.*` namespace, call `render_layout(__file__, {...})` and reference those keys directly in the template.
+
+Example:
+
+```python
+from casp.layout import render_layout
+
+def layout():
+  return render_layout(__file__, {"my_class": "size-8"})
+```
+
+In that pattern, the matching `layout.html` reads `[[ my_class ]]`, not `[[ layout.my_class ]]`, because the template string was already rendered before the nested layout pipeline continues.
+
+If you need both a custom layout string and standard `[[ layout.* ]]` props, return a tuple:
+
+```python
+from casp.layout import render_layout
+
+def layout():
+  return (
+    render_layout(__file__),
+    {"dashboard_body_class": "w-screen h-screen overflow-hidden"},
+  )
+```
+
 `layout()` currently runs synchronously in `casp.layout`. If you need async I/O, load it in `page()` instead of `layout.py`.
 
 Use [metadata.md](./metadata.md) when a layout also needs SEO defaults. Return dictionaries from `layout()` for visual or template props, and use `Metadata(...)` for title, description, and social tags.
@@ -344,6 +410,8 @@ If an AI agent is choosing where to add or update route code, apply these rules
 - Add `index.py` only when the same route needs metadata or server behavior; do not place route HTML in `index.py`.
 - Use [cache.md](./cache.md) when an `index.py` route should opt into page-level HTML caching.
 - Use `layout.html` for shared wrappers and `layout.py` for layout-level synchronous props or metadata.
+- When one route needs to change a parent layout, return `(render_page(__file__, ...), {"dashboard_body_class": ...})` from `page()` and read that value as `[[ layout.dashboard_body_class ]]` in the wrapping `layout.html`.
+- Use `layout.py` for layout props that should apply across an entire subtree. Use `render_layout(__file__, {...})` only when the layout should consume direct local variables such as `[[ my_class ]]` instead of the standard `[[ layout.* ]]` namespace.
 - Keep `<!-- @import ... -->` directives at the top of `index.html` and `layout.html`, above the single authored root element.
 - Use [metadata.md](./metadata.md) when a route or layout needs SEO fields.
 - Use `[segment]` for single dynamic parameters.

package/package.json

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