caspian-utils 0.0.5 → 0.0.7

package/dist/docs/components.md

@@ -53,7 +53,7 @@ Notes:
 
 ## Import And Use Components
 
-Import components inside the HTML template where they are used.
+Place component imports at the top of the HTML template, above the authored root element.
 
 ```html
 <!-- @import Container from "../components" -->
@@ -65,9 +65,66 @@ Import components inside the HTML template where they are used.
 
 The import comment is the bridge between the Python component file and the JSX-style tag.
 
+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 />`.
 - 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.
+
+Good:
+
+```html
+<!-- @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>
+</section>
+```
+
+Bad:
+
+```html
+<section class="auth-panel auth-panel-compact fade-up">
+  <!-- @import { Button, Input, Label } from "../../../lib/maddex" -->
+  <Label>Email</Label>
+</section>
+```
+
+### Same-File Component Exports
+
+Caspian does not require one Python file per component. A single file can export a main component plus related subcomponents.
+
+If `Breadcrumb.py` defines `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, and `BreadcrumbSeparator`, import those names from `Breadcrumb.py` itself.
+
+```html
+<!-- @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>
+</div>
+```
+
+If you only need one component from that file, keep the same file path:
+
+```html
+<!-- @import Breadcrumb from "../maddex/Breadcrumb.py" -->
+```
+
+Do not invent folder-level imports for symbols that do not have their own file. If `BreadcrumbItem` lives inside `Breadcrumb.py`, import it from `Breadcrumb.py`, not from `../maddex` as if `BreadcrumbItem.py` existed.
 
 ## Template-Backed Components
 
@@ -161,6 +218,8 @@ Every component HTML template must render exactly one top-level lowercase HTML e
 
 The same rule applies to route templates such as `src/app/**/index.html`: one root element, no sibling roots, and no manual `pp-component` authoring.
 
+Top-of-file `<!-- @import ... -->` directives are allowed before that root element and do not violate the single-root rule.
+
 This is not just style guidance. The installed compiler injects `pp-component` onto the root element, and it raises an error when the template has no root, multiple sibling roots, stray top-level text, or a component tag as the root.
 
 For AI-generated templates, treat this as a hard authoring rule: write the HTML the same way a React component returns one parent element. If the template needs a PulsePoint script, keep that script inside the same parent root.

package/dist/docs/index.md

@@ -58,7 +58,7 @@ Preferred lookup order:
 1. Read `node_modules/caspian-utils/dist/docs/index.md` to discover available local docs.
 2. Read `./caspian.config.json` before making any feature assumption. Use it to confirm which project capabilities are enabled and which directories or tooling rules apply.
 3. Read `database.md` for Prisma setup and ORM usage, `auth.md` for session auth and route protection, `components.md` for reusable UI authoring, `pulsepoint.md` for browser-side reactive runtime behavior, `fetch-data.md` for data flows, `state.md` for transient request-scoped state, `cache.md` for page caching, and `validation.md` for input boundaries.
-4. For authored component, route, and layout HTML files, generate exactly one top-level lowercase HTML element. Think React-style single parent wrapper: keep any owned PulsePoint logic in a plain `<script>` inside that root, and do not handwrite `pp-component="..."` or `type="text/pp"` because Caspian injects those runtime attributes automatically.
+4. For authored component, route, and layout HTML files, generate exactly one top-level lowercase HTML element. Think React-style single parent wrapper: keep any owned PulsePoint logic in a plain `<script>` inside that root, do not handwrite `pp-component="..."` or `type="text/pp"` because Caspian injects those runtime attributes automatically, and treat `<!-- @import ... -->` comments as file-level directives that belong above the authored root element instead of inside `<div>`, `<section>`, or `<html>`. When several component tags come from one Python file, import them from that exact file path, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`.
 5. Prefer local docs before generating code, commands, or migration guidance.
 6. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
 7. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.

package/dist/docs/project-structure.md

@@ -98,6 +98,8 @@ Use this folder for reusable UI components that should be imported into route te
 
 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.
 
+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.
+
 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.
 
 Do not handwrite `pp-component="..."` or `type="text/pp"` in component source templates either. Write plain `<script>` inside the single root and let the render pipeline inject the runtime shape.
@@ -161,6 +163,8 @@ The project auth configuration file. Use this path when changing authentication
 
 The root layout shared across pages.
 
+If this layout imports reusable components, place each `<!-- @import ... -->` comment above the authored root `<html>` element instead of nesting the comment inside `<html>` or `<body>`.
+
 ### `src/app/index.py`
 
 The backend logic for the route. This is where route behavior can load first-render data, expose `@rpc()` actions, and import framework features such as auth helpers, `casp.validate`, and route-level `Cache(...)` declarations.
@@ -169,6 +173,8 @@ The backend logic for the route. This is where route behavior can load first-ren
 
 The route template. It supports standard HTML, `<!-- @import ... -->` component imports, and PulsePoint directives, and it should be the default place for reactive frontend behavior in Caspian.
 
+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.
 
 ### `src/app/globals.css`
@@ -198,6 +204,7 @@ If an AI agent is deciding where to make changes, use these rules first.
 - Put route templates and route-specific backend logic in `src/app/`.
 - 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.
+- Keep `<!-- @import ... -->` comments above the single authored root element in route, layout, and component HTML files.
 - For route and component HTML files, always emit one top-level lowercase HTML element. Good: one wrapper containing the content and a plain `<script>` when needed. Bad: a wrapper element followed by a sibling top-level `<script>`, or handwritten `pp-component="..."` and `type="text/pp"` attributes in source.
 - Put shared helpers and reusable libraries in `src/lib/`.
 - Use PulsePoint conventions in route templates for reactive frontend behavior.

package/dist/docs/routing.md

@@ -76,6 +76,8 @@ Use `index.html` for the route template. This is the route's view layer.
 
 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.
 
+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.
+
 Do not manually add `pp-component="..."` to the route root. The Python render pipeline injects that attribute onto the route's single top-level lowercase HTML element.
 
 Do not manually add `type="text/pp"` to a route-owned script either. In source templates, write a plain `<script>` inside the root and let `main.py` call `transform_scripts(...)` before the browser runtime sees the HTML.
@@ -108,6 +110,15 @@ Bad:
 </script>
 ```
 
+Also bad:
+
+```html
+<section class="dashboard-shell">
+  <!-- @import StatsCard from "../components" -->
+  <StatsCard title="Users" value="42" />
+</section>
+```
+
 Example authored route template:
 
 ```html
@@ -219,6 +230,8 @@ Route groups are useful when you want to:
 
 Layouts work like the Next.js App Router layout system. A `layout.html` file wraps the routes beneath its folder, and nested layouts compose automatically.
 
+When a layout imports components, keep each `<!-- @import ... -->` comment above the layout's authored wrapper element, such as the root `<section>` in a nested layout or the root `<html>` in the app layout.
+
 Resolved SEO fields are exposed to layouts as `[[ metadata.* ]]`, while values returned from `layout.py` are exposed separately as `[[ layout.* ]]`.
 
 For example, a page inside `/dashboard/settings` is wrapped by the root layout first and then by the dashboard layout.
@@ -300,6 +313,7 @@ If an AI agent is choosing where to add or update route code, apply these rules
 - Use `index.html` for route templates and `index.py` for route-level async logic.
 - 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.
+- 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.
 - Use `[...segment]` for catch-all route matching.

package/package.json

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