@betterportal/theme-embedded 10.6.17 → 10.6.19

package/bp-resources/SKILL.md

@@ -5,7 +5,7 @@ description: Build compact BetterPortal service UI for the Embedded theme.
 
 # BetterPortal Embedded UI
 
-1. Read `/llms-api.txt` and the Embedded UI guide.
+1. Read `/llms-api.txt`, `/llms-ui.txt` and the Embedded UI guide.
 2. Keep the view single-column and self-contained.
 3. Use semantic HTML and server-rendered HTMX fragments.
 4. In renderers, use `ctx.url.route()` for service calls and `ctx.url.uiRoute()` only for GET navigation. Pass a declared dependency alias as `serviceId` for another service.
@@ -13,3 +13,5 @@ description: Build compact BetterPortal service UI for the Embedded theme.
 6. Verify keyboard use, labels, responsive wrapping and the published schemas.
 
 Do not recreate Bootstrap components or a second app shell. Recommend Bootstrap1 when the requested interface genuinely needs those primitives.
+
+Read the UI guide's colors/appearance section and linked BetterPortal documentation; use the active theme's semantic roles and installed API version. Before delivery, follow its view boundaries and defect-reporting rules. Keep domain work in handlers, never submit during initialization or draft restoration, and never register HTMX extensions from service markup. Preserve schema-backed HTML5 constraints: use native submission or `requestSubmit()`, gate custom triggers with `reportValidity()`, and never disable validation to post an invalid form. Use project reporting tools for reproducible theme/framework defects. Verify failed POST followed by navigation, preload, history and repeated swaps without mutation replay or duplicate listeners.

package/bp-resources/page-template.tsx

@@ -1,7 +1,7 @@
 /** @jsxImportSource jsx-htmx */
-import type { PageRenderer } from "@betterportal/framework";
+import type { RegisteredViewRenderer } from "@betterportal/framework";
 
-export const render: PageRenderer = (data) => (
+export const render: RegisteredViewRenderer["render"] = (data) => (
   <section aria-labelledby="page-title">
     <h1 id="page-title">Page title</h1>
     <p>Explain the task in one sentence.</p>

package/bp-resources/ui-guide.md

@@ -14,3 +14,32 @@ The Embedded theme renders BetterPortal service content inside a lightweight hos
 - Do not add a SPA framework, iframe, client router, state library or hardcoded service URL.
 
 The Embedded theme deliberately offers fewer visual primitives than Bootstrap1. If a workflow needs a complex application shell, use Bootstrap1 instead of recreating a shell inside service content.
+
+## Colors and appearance
+
+Embedded is a minimal host with a transparent document background. It does not declare the Bootstrap1/2 palette configuration or their `--bp-*` token contract. A `bootstrap5` component example or a brand hex value from another theme is not a portable Embedded styling API.
+
+Use native controls and inherit available host typography/colors; keep necessary service-specific CSS local to the component. Do not load Bootstrap, add global branding, redefine document colors or install a separate appearance controller. If a richer palette/component contract is required, implement it in the owning theme or select a suitable theme, rather than reproducing its shell in a view.
+
+Read the [BetterPortal theme contract](https://github.com/BetterCorp/BetterPortal/blob/master/docs/building/themes.md), [routes/views](https://github.com/BetterCorp/BetterPortal/blob/master/docs/building/routes-and-views.md) and active `/llms-ui.txt`. Match documentation examples to installed package versions; master may describe newer APIs.
+
+## Form validation before requests
+
+The backend input schema is the source of truth. Render its applicable HTML5 constraints (`type`, `required`, `min`, `max`, `step`, `minlength`, `maxlength`, `pattern`) and preserve them after swaps. The browser validates the returned HTML controls; it does not execute AnyVali/JSON schema automatically. Numeric inputs use range/step constraints, not `pattern`. Hidden inputs and controls barred from constraint validation are not checked by these APIs; validate computed payloads against the published input contract and always on the server.
+
+Prefer native submit buttons or `form.requestSubmit(submitter)`. For a necessary custom trigger, stop if `form.reportValidity()` is false; `form.checkValidity()` checks without showing validation messages. Never bypass invalid controls with `form.submit()`, synthetic submit events, custom fetch/HTMX posts, `noValidate`/`formNoValidate`, `novalidate`/`formnovalidate` or disabled HTMX validation. Recalculation that accepts fewer fields needs a separate non-nested form/component with its own constraints, not a bypass on the full form. The backend validates every submission, including rules HTML cannot express.
+
+Check invalid submissions by button, Enter and custom triggers: no POST is sent; a valid form submits once. See [HTML form validation and view guidance](https://github.com/BetterCorp/BetterPortal/blob/master/docs/building/themes.md#preserve-html5-form-validation).
+
+## View boundaries and defect reporting
+
+Read the shared `/llms-ui.txt` rules before implementing a view.
+
+- Render typed handler data. Keep business defaults, validation, calculations, persistence and report generation in handlers/domain helpers; HTML constraints are presentation hints.
+- Initialization, history navigation, prefetched insertion and draft restoration must not submit forms or replay mutations. Keep recalculation and final submission explicit; do not retain one-shot action flags after failure or cancellation.
+- The shell owns HTMX 4 and its bundled `bp-shell, sse` extensions. Do not inject extension assets, register extensions or add unsupported `hx-ext` values. Use supported form encoding and report schema/serialization gaps upstream.
+- Prefer native controls, HTMX triggers, `hx-indicator` and HTMX 4 `hx-disable`. Necessary local scripts use typed `js(() => ...)`, component-scoped selectors, idempotent binding and cleanup on removal. Do not add global submit functions or repeated document-wide listeners. HTMX 2 camelCase lifecycle events are incompatible with the installed HTMX 4 runtime.
+- Browser drafts require an explicit schema, allowed fields, tenant/app/service/user scope, version, expiry and clearing rules. Validate restoration, exclude action/auth fields, and never generate hidden inputs from arbitrary stored keys. Restore without submitting; browser owner metadata is not authorization.
+- Use project issue/reporting tools for reproducible theme/framework defects. Include versions, minimal reproduction, expected/actual behavior and relevant request initiators or computed styles without credentials or customer data. Check existing reports; if access is unavailable, provide a ready-to-file report. Do not replace theme defaults with hardcoded palettes, `!important` patches, duplicate navigation or runtime workarounds.
+- Service errors use handler-side `ctx.diagnostic({ code, reason, attributes? })` before responses outside HTTP 200-399; the view displays a safe error state. Diagnostics do not replace upstream defect reports.
+- Verify failed POST then navigation, Back/Forward, preload, repeated swaps and stale drafts. Inspect request initiators and confirm navigation/restoration never mutates or leaves controls disabled.

package/lib/bp-contracts/org.betterportal.theme.embedded.json

@@ -4,7 +4,7 @@
     "pluginId": "org.betterportal.theme.embedded",
     "title": "Embedded Theme",
     "description": "Minimal htmx theme for embedding BetterPortal content without iframes.",
-    "version": "10.6.17",
+    "version": "10.6.19",
     "category": "theme",
     "deploymentModes": [
       "self-hosted"
@@ -33,7 +33,7 @@
         "title": "Embedded UI guide",
         "description": "Compact layout, HTMX and accessibility rules for embedded views.",
         "mediaType": "text/markdown; charset=utf-8",
-        "content": "# Embedded theme UI guide\n\nThe Embedded theme renders BetterPortal service content inside a lightweight host without an iframe. Keep UI narrow, self-contained and dependent only on native HTML, HTMX and the theme's existing variables.\n\n## Rules\n\n- Return service content only; the theme owns the host document and main outlet.\n- Use semantic HTML, visible labels, keyboard-operable controls and responsive wrapping.\n- Prefer one column. Avoid persistent navigation, wide tables, fixed positioning and viewport-sized panels.\n- In renderers, use `ctx.url.route()` for service requests. Use `ctx.url.uiRoute()` only for GET page navigation. Pass a declared dependency alias as `serviceId` when resolving another app-mounted service. Handler equivalents are `ctx.routeUrl()` and `ctx.uiRouteUrl()`.\n- Plain internal `<a href=\"/route\">` links and GET/POST forms are automatically upgraded to HTMX and routed through the owning service. A bare `<form>` posts to the current service view. Use `bp-no-override` or `data-bp-no-override` on an element or ancestor only when native browser behavior is intentional.\n- Use normal forms and HTMX swaps. Provide loading, empty, validation and error states.\n- Use `hx-download` for authenticated files and `HX-Trigger` events for passive refresh.\n- Do not add a SPA framework, iframe, client router, state library or hardcoded service URL.\n\nThe Embedded theme deliberately offers fewer visual primitives than Bootstrap1. If a workflow needs a complex application shell, use Bootstrap1 instead of recreating a shell inside service content.\n"
+        "content": "# Embedded theme UI guide\n\nThe Embedded theme renders BetterPortal service content inside a lightweight host without an iframe. Keep UI narrow, self-contained and dependent only on native HTML, HTMX and the theme's existing variables.\n\n## Rules\n\n- Return service content only; the theme owns the host document and main outlet.\n- Use semantic HTML, visible labels, keyboard-operable controls and responsive wrapping.\n- Prefer one column. Avoid persistent navigation, wide tables, fixed positioning and viewport-sized panels.\n- In renderers, use `ctx.url.route()` for service requests. Use `ctx.url.uiRoute()` only for GET page navigation. Pass a declared dependency alias as `serviceId` when resolving another app-mounted service. Handler equivalents are `ctx.routeUrl()` and `ctx.uiRouteUrl()`.\n- Plain internal `<a href=\"/route\">` links and GET/POST forms are automatically upgraded to HTMX and routed through the owning service. A bare `<form>` posts to the current service view. Use `bp-no-override` or `data-bp-no-override` on an element or ancestor only when native browser behavior is intentional.\n- Use normal forms and HTMX swaps. Provide loading, empty, validation and error states.\n- Use `hx-download` for authenticated files and `HX-Trigger` events for passive refresh.\n- Do not add a SPA framework, iframe, client router, state library or hardcoded service URL.\n\nThe Embedded theme deliberately offers fewer visual primitives than Bootstrap1. If a workflow needs a complex application shell, use Bootstrap1 instead of recreating a shell inside service content.\n\n## Colors and appearance\n\nEmbedded is a minimal host with a transparent document background. It does not declare the Bootstrap1/2 palette configuration or their `--bp-*` token contract. A `bootstrap5` component example or a brand hex value from another theme is not a portable Embedded styling API.\n\nUse native controls and inherit available host typography/colors; keep necessary service-specific CSS local to the component. Do not load Bootstrap, add global branding, redefine document colors or install a separate appearance controller. If a richer palette/component contract is required, implement it in the owning theme or select a suitable theme, rather than reproducing its shell in a view.\n\nRead the [BetterPortal theme contract](https://github.com/BetterCorp/BetterPortal/blob/master/docs/building/themes.md), [routes/views](https://github.com/BetterCorp/BetterPortal/blob/master/docs/building/routes-and-views.md) and active `/llms-ui.txt`. Match documentation examples to installed package versions; master may describe newer APIs.\n\n## Form validation before requests\n\nThe backend input schema is the source of truth. Render its applicable HTML5 constraints (`type`, `required`, `min`, `max`, `step`, `minlength`, `maxlength`, `pattern`) and preserve them after swaps. The browser validates the returned HTML controls; it does not execute AnyVali/JSON schema automatically. Numeric inputs use range/step constraints, not `pattern`. Hidden inputs and controls barred from constraint validation are not checked by these APIs; validate computed payloads against the published input contract and always on the server.\n\nPrefer native submit buttons or `form.requestSubmit(submitter)`. For a necessary custom trigger, stop if `form.reportValidity()` is false; `form.checkValidity()` checks without showing validation messages. Never bypass invalid controls with `form.submit()`, synthetic submit events, custom fetch/HTMX posts, `noValidate`/`formNoValidate`, `novalidate`/`formnovalidate` or disabled HTMX validation. Recalculation that accepts fewer fields needs a separate non-nested form/component with its own constraints, not a bypass on the full form. The backend validates every submission, including rules HTML cannot express.\n\nCheck invalid submissions by button, Enter and custom triggers: no POST is sent; a valid form submits once. See [HTML form validation and view guidance](https://github.com/BetterCorp/BetterPortal/blob/master/docs/building/themes.md#preserve-html5-form-validation).\n\n## View boundaries and defect reporting\n\nRead the shared `/llms-ui.txt` rules before implementing a view.\n\n- Render typed handler data. Keep business defaults, validation, calculations, persistence and report generation in handlers/domain helpers; HTML constraints are presentation hints.\n- Initialization, history navigation, prefetched insertion and draft restoration must not submit forms or replay mutations. Keep recalculation and final submission explicit; do not retain one-shot action flags after failure or cancellation.\n- The shell owns HTMX 4 and its bundled `bp-shell, sse` extensions. Do not inject extension assets, register extensions or add unsupported `hx-ext` values. Use supported form encoding and report schema/serialization gaps upstream.\n- Prefer native controls, HTMX triggers, `hx-indicator` and HTMX 4 `hx-disable`. Necessary local scripts use typed `js(() => ...)`, component-scoped selectors, idempotent binding and cleanup on removal. Do not add global submit functions or repeated document-wide listeners. HTMX 2 camelCase lifecycle events are incompatible with the installed HTMX 4 runtime.\n- Browser drafts require an explicit schema, allowed fields, tenant/app/service/user scope, version, expiry and clearing rules. Validate restoration, exclude action/auth fields, and never generate hidden inputs from arbitrary stored keys. Restore without submitting; browser owner metadata is not authorization.\n- Use project issue/reporting tools for reproducible theme/framework defects. Include versions, minimal reproduction, expected/actual behavior and relevant request initiators or computed styles without credentials or customer data. Check existing reports; if access is unavailable, provide a ready-to-file report. Do not replace theme defaults with hardcoded palettes, `!important` patches, duplicate navigation or runtime workarounds.\n- Service errors use handler-side `ctx.diagnostic({ code, reason, attributes? })` before responses outside HTTP 200-399; the view displays a safe error state. Diagnostics do not replace upstream defect reports.\n- Verify failed POST then navigation, Back/Forward, preload, repeated swaps and stale drafts. Inspect request initiators and confirm navigation/restoration never mutates or leaves controls disabled.\n"
       },
       {
         "id": "embedded.skill",
@@ -41,7 +41,7 @@
         "title": "Embedded UI skill",
         "description": "Agent workflow for producing Embedded-compatible service UI.",
         "mediaType": "text/markdown; charset=utf-8",
-        "content": "---\nname: betterportal-embedded-ui\ndescription: Build compact BetterPortal service UI for the Embedded theme.\n---\n\n# BetterPortal Embedded UI\n\n1. Read `/llms-api.txt` and the Embedded UI guide.\n2. Keep the view single-column and self-contained.\n3. Use semantic HTML and server-rendered HTMX fragments.\n4. In renderers, use `ctx.url.route()` for service calls and `ctx.url.uiRoute()` only for GET navigation. Pass a declared dependency alias as `serviceId` for another service.\n5. Include loading, empty, validation and failure states.\n6. Verify keyboard use, labels, responsive wrapping and the published schemas.\n\nDo not recreate Bootstrap components or a second app shell. Recommend Bootstrap1 when the requested interface genuinely needs those primitives.\n"
+        "content": "---\nname: betterportal-embedded-ui\ndescription: Build compact BetterPortal service UI for the Embedded theme.\n---\n\n# BetterPortal Embedded UI\n\n1. Read `/llms-api.txt`, `/llms-ui.txt` and the Embedded UI guide.\n2. Keep the view single-column and self-contained.\n3. Use semantic HTML and server-rendered HTMX fragments.\n4. In renderers, use `ctx.url.route()` for service calls and `ctx.url.uiRoute()` only for GET navigation. Pass a declared dependency alias as `serviceId` for another service.\n5. Include loading, empty, validation and failure states.\n6. Verify keyboard use, labels, responsive wrapping and the published schemas.\n\nDo not recreate Bootstrap components or a second app shell. Recommend Bootstrap1 when the requested interface genuinely needs those primitives.\n\nRead the UI guide's colors/appearance section and linked BetterPortal documentation; use the active theme's semantic roles and installed API version. Before delivery, follow its view boundaries and defect-reporting rules. Keep domain work in handlers, never submit during initialization or draft restoration, and never register HTMX extensions from service markup. Preserve schema-backed HTML5 constraints: use native submission or `requestSubmit()`, gate custom triggers with `reportValidity()`, and never disable validation to post an invalid form. Use project reporting tools for reproducible theme/framework defects. Verify failed POST followed by navigation, preload, history and repeated swaps without mutation replay or duplicate listeners.\n"
       },
       {
         "id": "embedded.page-template",
@@ -50,7 +50,7 @@
         "description": "Minimal server-rendered JSX page structure.",
         "mediaType": "text/plain; charset=utf-8",
         "language": "typescript",
-        "content": "/** @jsxImportSource jsx-htmx */\nimport type { PageRenderer } from \"@betterportal/framework\";\n\nexport const render: PageRenderer = (data) => (\n  <section aria-labelledby=\"page-title\">\n    <h1 id=\"page-title\">Page title</h1>\n    <p>Explain the task in one sentence.</p>\n    <div>{JSON.stringify(data)}</div>\n  </section>\n);\n"
+        "content": "/** @jsxImportSource jsx-htmx */\nimport type { RegisteredViewRenderer } from \"@betterportal/framework\";\n\nexport const render: RegisteredViewRenderer[\"render\"] = (data) => (\n  <section aria-labelledby=\"page-title\">\n    <h1 id=\"page-title\">Page title</h1>\n    <p>Explain the task in one sentence.</p>\n    <div>{JSON.stringify(data)}</div>\n  </section>\n);\n"
       }
     ],
     "shell": {

package/lib/schemas/service-betterportal-theme-embedded.json

@@ -2,7 +2,7 @@
   "pluginId": "service-betterportal-theme-embedded",
   "pluginName": "service-betterportal-theme-embedded",
   "events": {},
-  "version": "10.6.17",
+  "version": "10.6.19",
   "configSchema": {
     "anyvaliVersion": "1.0",
     "schemaVersion": "1.1",

package/lib/schemas/service-betterportal-theme-embedded.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "service-betterportal-theme-embedded",
   "name": "service-betterportal-theme-embedded",
-  "version": "10.6.17",
+  "version": "10.6.19",
   "description": "Embedded BetterPortal theme",
   "category": "service",
   "tags": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@betterportal/theme-embedded",
-  "version": "10.6.17",
+  "version": "10.6.19",
   "description": "BetterPortal v10 embedded theme plugin for Node.js",
   "main": "lib/index.js",
   "types": "src/index.ts",
@@ -32,9 +32,9 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@betterportal/framework": "10.6.17",
-    "@betterportal/plugin-bsb": "10.6.17",
-    "@betterportal/theme-runtime": "10.6.17",
+    "@betterportal/framework": "10.6.19",
+    "@betterportal/plugin-bsb": "10.6.19",
+    "@betterportal/theme-runtime": "10.6.19",
     "@bsb/base": "^9.7.0",
     "anyvali": "^1.1.5",
     "jsx-htmx": "4.0.0"