caspian-utils 0.0.20 → 0.0.22

package/dist/docs/fetch-data.md

@@ -236,9 +236,10 @@ Use this pattern for real file managers:
 
 - Keep upload and delete actions in the owning route `index.py`, not in `main.py`.
 - Use `page()` to render the initial manager payload.
-- Store durable metadata in Prisma and store the browser-accessible blob separately under `public/assets/file-manager/`.
+- Store durable metadata in Prisma and store the browser-accessible blob separately under a public upload directory such as `public/uploads/`.
+- Create `public/uploads` on demand in the shared helper if the directory does not exist yet.
 - Use `pp.state(...)` plus `pp-for` for the list UI instead of manual `innerHTML` writes.
-- Add `public/assets/file-manager` to `PUBLIC_IGNORE_DIRS` in `settings/bs-config.ts` so runtime uploads do not trigger BrowserSync reloads during `npm run dev`.
+- Add the public-root-relative directory name `uploads` to `PUBLIC_IGNORE_DIRS` in `settings/bs-config.ts` when `public/uploads/` is the active upload root so runtime uploads do not trigger BrowserSync reloads during `npm run dev`.
 
 Read [file-uploads.md](./file-uploads.md) for the complete file-manager pattern.
 

package/dist/docs/file-uploads.md

@@ -23,7 +23,8 @@ Treat uploads as normal route behavior. Keep the owning browser UI in the route
 - Keep first-render file manager data in `page()` so the initial HTML already contains the current asset list and storage summary.
 - Keep upload and delete actions in the route's `index.py`; do not move ordinary upload flows into `main.py`.
 - Keep reusable file-manager helpers in `src/lib/`.
-- Store uploaded blobs under a project-owned public directory such as `public/storage/...` when the files should be browser-accessible.
+- Store uploaded blobs under a project-owned public directory such as `public/uploads/...` when the files should be browser-accessible.
+- Create the upload directory on demand in the shared helper when it does not exist yet; do not assume the folder is committed.
 - Store durable metadata in Prisma, not in JSON manifests or ad hoc metadata files.
 - Use `pp.state(...)` plus `pp-for` to render and update the file list from returned server payloads.
 - Use `onUploadProgress` only for progress UI; let the RPC return refreshed manager data for the authoritative post-upload state.
@@ -36,7 +37,7 @@ Treat uploads as normal route behavior. Keep the owning browser UI in the route
 | Upload and delete `@rpc()` actions | `src/app/**/index.py` | Keep these route-local so they stay close to the owning page. |
 | Shared storage, normalization, and persistence helpers | `src/lib/**` | Reuse helpers across routes without pushing route behavior into app bootstrap. |
 | Upload metadata model | `prisma/schema.prisma` | Persist owner, file name, MIME type, path, size, collection, and timestamps in Prisma. |
-| Browser-accessible uploaded blobs | `public/storage/**` or another app-owned public directory | Keep the public path predictable and derived from stored metadata. |
+| Browser-accessible uploaded blobs | `public/uploads/**` or another app-owned public directory | Keep the public path predictable and derived from stored metadata, and create the directory on demand if it may not exist yet. |
 | BrowserSync upload ignore | `settings/bs-config.ts` | Keep the active public upload directory in `PUBLIC_IGNORE_DIRS`. |
 
 ## Route Flow
@@ -143,15 +144,17 @@ Typical metadata fields include:
 
 ## BrowserSync And Uploaded Public Files
 
-If runtime uploads write into `public/assets/file-manager/`, BrowserSync should ignore that directory during local development. Otherwise every upload can trigger a full browser reload.
+If runtime uploads write into `public/uploads/`, BrowserSync should ignore that directory during local development. Otherwise every upload can trigger a full browser reload.
 
-Use a workspace-relative ignore entry in `settings/bs-config.ts`:
+The helper that stores uploaded files should create `public/uploads` before writing the first file when the directory is not present yet.
+
+Use a public-root-relative ignore entry in `settings/bs-config.ts`:
 
 ```ts
-const PUBLIC_IGNORE_DIRS = ["public/assets/file-manager"];
+const PUBLIC_IGNORE_DIRS = ["uploads"];
 ```
 
-Match those entries against workspace-relative paths so nested uploads such as `public/assets/file-manager/user-1/media/example.png` are ignored too.
+`settings/bs-config.ts` matches those entries against paths relative to the `public/` root, so nested uploads such as `uploads/user-1/media/example.png` are ignored too.
 
 ## What To Avoid
 
@@ -167,5 +170,5 @@ Match those entries against workspace-relative paths so nested uploads such as `
 - Use `fetch-data.md` for the route-render versus RPC split.
 - Use `database.md` when Prisma models or relations must change for upload metadata.
 - Use `validation.md` for MIME, extension, and other boundary checks, then keep explicit size and auth checks in the owning RPC action.
-- Use `project-structure.md` for placement rules, especially `src/app/` versus `src/lib/` and `public/assets/file-manager/`.
+- Use `project-structure.md` for placement rules, especially `src/app/` versus `src/lib/` and `public/uploads/`.
 - Use `commands.md` and `settings/bs-config.ts` when uploads should not trigger BrowserSync reloads during `npm run dev`.

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/project-structure.md

@@ -172,7 +172,9 @@ This folder contains your database model definitions in `schema.prisma` and any
 
 Store static assets here, including images, fonts, and generated frontend assets that should be served directly.
 
-Runtime-uploaded public blobs can also live here. Confirm the actual upload path in the project code and keep that directory aligned with any BrowserSync ignore rules.
+Runtime-uploaded public blobs can also live here. Confirm the actual upload path in the project code, commonly `public/uploads/`, and keep that directory aligned with any BrowserSync ignore rules.
+
+If the upload directory is created only at runtime, create it on demand in the owning upload helper instead of assuming it is already committed.
 
 If the local BrowserSync stack is running, keep that upload directory in `settings/bs-config.ts` `PUBLIC_IGNORE_DIRS` so new uploads do not force a full browser reload.
 
@@ -205,7 +207,9 @@ Read the actual values in `caspian.config.json` instead of inferring feature sta
 
 The BrowserSync watcher configuration for the local stack lives here.
 
-When runtime uploads write into `public/assets/file-manager/`, keep `public/assets/file-manager` in `PUBLIC_IGNORE_DIRS` and match it against workspace-relative paths so nested uploaded files do not trigger reloads.
+When runtime uploads write into `public/uploads/`, keep the public-root-relative entry `uploads` in `PUBLIC_IGNORE_DIRS`.
+
+`settings/bs-config.ts` matches ignore entries against paths relative to the `public/` root, so nested uploaded files do not trigger reloads.
 
 ### `src/lib/auth/auth_config.py`
 

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.20",
+  "version": "0.0.22",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {