cabloy 5.1.134 → 5.1.136

package/.cabloy-version

@@ -1 +1 @@
-5.1.134
+5.1.136

package/.claude/skills/cabloy-backend-scaffold/SKILL.md

@@ -117,6 +117,15 @@ Typical backend thread pieces include:
 
 Do not throw away the generated structure and rewrite it from scratch unless the generator clearly does not match the task.
 
+### Generated renderer decision
+
+When refining generated entity fields, choose form and table controls from business semantics, not only from the primitive TypeScript type:
+
+- keep ordinary Cabloy Basic text fields, such as generated `name` and `description`, on the implicit default `Input` renderer; do not mechanically add `basic-input:formFieldInput`
+- add explicit `ZovaRender.field(...)` when semantics require a specialized control, such as an enum/select, resource relation, date/time, boolean choice, money, image, or file
+- add `ZovaRender.cell(...)` when that field also needs specialized table presentation
+- reuse a shared renderer first, configure it with field-level options next, and create a custom renderer only when the shared surface cannot express the required behavior; follow `cabloy-resource-field-update` for the edition-aware renderer branch
+
 ## Step 5: Apply backend follow-up logic deliberately
 
 Backend scaffolding is rarely complete after file generation alone. Treat this follow-up review as mandatory.

package/.claude/skills/cabloy-zova-source-reading/SKILL.md

@@ -82,6 +82,9 @@ Start from the public frontend reading docs in `cabloy-docs/frontend/`.
 - `cabloy-docs/frontend/zova-vs-vue3-comparison.md`
 - `cabloy-docs/frontend/zova-reactivity-under-the-hood.md`
 - `cabloy-docs/frontend/zova-source-reading-map.md`
+- `cabloy-docs/frontend/page-guide.md`
+- `cabloy-docs/frontend/component-guide.md`
+- `cabloy-docs/frontend/css-in-js-guide.md`
 
 For compact procedural summaries inside the skill bundle, also use:
 
@@ -142,7 +145,27 @@ Do **not** lead with statements like:
 
 Those translations can erase the actual Zova architecture.
 
-For component-wrapper questions specifically, remember that `controllerRef` exposes the controller instance, not a generic DOM ref, and should not be treated as a generic Vue component-ref substitute without checking the current wrapper/controller source path.
+For component-wrapper questions specifically, remember that `controllerRef` exposes the controller instance to the component consumer, not a generic DOM ref, and should not be treated as a generic Vue component-ref substitute without checking the current wrapper/controller source path.
+
+### Split Controller, Render, and Style access
+
+When explaining a split page or component, establish role ownership before discussing access:
+
+- Controller owns state, actions, and lifecycle work.
+- Render owns TSX composition.
+- Style owns scoped CSS-in-JS setup.
+
+The source-confirmed direct member lookup order is:
+
+| Current bean | Direct member lookup order |
+| --- | --- |
+| Controller | Controller only |
+| Style | Style, then Controller |
+| Render | Render, then Controller, then Style |
+
+State the shadowing caveat: an own member on the current bean takes precedence over each fallback surface. Recommend `this.member` for ordinary same-component companion access, such as Render reading Controller state or a Style-generated class.
+
+Distinguish this normal fallback from explicit `@Use()` or bean/container access. Use explicit access only when the task needs a named or specific instance, selector or scope boundary, identity passing, lifecycle control, or other interop. Do not confuse generated type augmentation with runtime behavior: generated interfaces expose the type surface, while proxy fallback supplies missing companion members at runtime.
 
 ## Step 6: Distinguish source-confirmed behavior from interpretive comparison
 

package/.claude/skills/cabloy-zova-source-reading/references/analysis-modes.md

@@ -46,6 +46,7 @@ Use this mode when the user is mainly asking:
    - model
    - behavior
    - SSR
+   - split Controller/Render/Style delegation
 3. trace the smallest current-source path that confirms the runtime behavior
 4. distinguish source-confirmed behavior from interpretation
 5. only after the Zova-native explanation is clear, add Vue analogy if helpful
@@ -57,6 +58,17 @@ Use this mode when the user is mainly asking:
 - what triggers the behavior
 - what is source-confirmed
 
+### Companion delegation response sequence
+
+For questions about a split Controller, Render, and Style implementation:
+
+1. establish role ownership: Controller for state/actions/lifecycle, Render for TSX composition, Style for scoped CSS-in-JS
+2. give the direct lookup order: Controller only; Style then Controller; Render then Controller then Style
+3. state that an own member shadows the next fallback surface
+4. recommend direct `this.member` access for ordinary same-component access
+5. distinguish generated type augmentation from proxy-based runtime fallback
+6. reserve `@Use()` or explicit bean/container access for named/specific identity, selectors/scopes, lifecycle control, or interop
+
 ## Mode C: Vue-vs-Zova comparison mode
 
 Use this mode when the user is mainly asking:

package/.claude/skills/cabloy-zova-source-reading/references/core-reading-paths.md

@@ -37,6 +37,34 @@ Use when the question is about:
 - `controllerRef`
 - component-local controller behavior
 
+## Split Controller, Render, and Style companion path
+
+Read in this order:
+
+1. `home-layoutadmin/src/.metadata/component/layoutAdmin.ts`
+2. `zova-core/src/composables/useController.ts`
+3. `zova-core/src/bean/beanStyleBase.ts`
+4. `zova-core/src/bean/beanControllerLike.ts`
+5. `zova-core/src/bean/beanRenderLike.ts`
+6. `zova-core/src/bean/beanContainer.ts`
+7. `zova-core/src/core/context/component.ts`
+
+Use when the question is about:
+
+- Render reading Controller state or actions through `this.member`
+- Style reading Controller state through `this.member`
+- Render consuming a Style-generated class such as `this.cClass`
+- generated typing versus runtime fallback
+- companion-member shadowing or explicit `@Use()` boundaries
+
+Expected conclusion:
+
+- generated metadata types Style as Controller and Render as Style, but that type composition is not the runtime mechanism
+- `useController(...)` creates Controller, Style, then Render in one context
+- Controller has no companion fallback; Style falls back to Controller; Render falls back to Controller, then Style
+- a locally declared member wins before fallback, so same-name members shadow companion members
+- use direct `this.member` for normal companion access; reserve explicit identity/container access for named instances, selector/scope boundaries, lifecycle control, or interop
+
 ## Bean lifecycle and helper API path
 
 Read in this order:

package/.github/workflows/playwright-e2e.yml

@@ -30,7 +30,7 @@ jobs:
         run: npm run test:e2e:basic:clean
       - name: upload Playwright artifacts
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: playwright-artifacts-basic
           path: |
@@ -68,7 +68,7 @@ jobs:
         run: npm run test:e2e:commerce:clean
       - name: upload Playwright artifacts
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: playwright-artifacts-commerce
           path: |

package/.github/workflows/vona-test-pg.yml

@@ -35,7 +35,7 @@ jobs:
       - name: init
         run: npm run init
       - name: run A-Pay focused gate
-        run: DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- test-pay/test/paymentSession.test.ts test-pay/test/payMock.test.ts test-pay/test/paypalProvider.test.ts test-pay/test/paypalLifecycle.test.ts test-pay/test/outbox.test.ts test-pay/test/webhook.test.ts --flavor=normal
+        run: DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- test-pay/test/paymentSession.test.ts test-pay/test/payMock.test.ts test-pay/test/paypalProvider.test.ts test-pay/test/paypalLifecycle.test.ts test-pay/test/stripeProvider.test.ts test-pay/test/stripeLifecycle.test.ts test-pay/test/outbox.test.ts test-pay/test/webhook.test.ts --flavor=normal
         working-directory: vona
       - name: run Commerce stock contention gate
         run: |

package/.github/workflows/vona-test-sqlite3.yml

@@ -28,7 +28,7 @@ jobs:
       - name: init
         run: npm run init
       - name: run A-Pay focused gate
-        run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run vona :bin:test -- test-pay/test/paymentSession.test.ts test-pay/test/payMock.test.ts test-pay/test/paypalProvider.test.ts test-pay/test/paypalLifecycle.test.ts test-pay/test/outbox.test.ts test-pay/test/webhook.test.ts --flavor=normal
+        run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run vona :bin:test -- test-pay/test/paymentSession.test.ts test-pay/test/payMock.test.ts test-pay/test/paypalProvider.test.ts test-pay/test/paypalLifecycle.test.ts test-pay/test/stripeProvider.test.ts test-pay/test/stripeLifecycle.test.ts test-pay/test/outbox.test.ts test-pay/test/webhook.test.ts --flavor=normal
         working-directory: vona
       - name: run Commerce payment, shipment, and refund lifecycle gate
         run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run vona :bin:test -- commerce-trade/test/paymentOutcome.test.ts commerce-trade/test/reservationExpiry.test.ts commerce-trade/test/shipment.test.ts commerce-trade/test/refundLifecycle.test.ts --flavor=normal

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 5.1.136
+
+### Features
+
+- Add route name support.
+- Support YouTube embeds in Markdown.
+- Update retryable behavior.
+- Add `getPagePath`.
+- Add block page support.
+- Render fields with improved support.
+- Add commerce locale support.
+- Add Markdown task lists, HTML, and CSS support.
+- Split Controller, Render, and Style companion access.
+- Add payment and Stripe integrations.
+- Add Stripe-hosted checkout payments.
+- Support disabled users.
+- Add locale support for SSR profiles and sessions.
+- Add locale support for role titles.
+
+### Bug Fixes
+
+- Fix end-to-end test issues.
+- Fix test error handling.
+- Resolve route resolution issues.
+
+### Improvements
+
+- Refactor Markdown handling.
+- Remove trailing whitespace from generated metadata.
+- Update Playwright workflows and dependencies.
+
+## 5.1.135
+
+### Improvements
+
+- Refresh the Zova lockfile after compensation rerun preparation.
+- Refresh the Vona Zova Core patch for v5.1.84.
+
 ## 5.1.134
 
 ### Features

package/CLAUDE.md

@@ -54,6 +54,7 @@ Before inventing a custom implementation path:
 - For frontend work, assume Cabloy Basic and Cabloy Start share a frontend engineering layer but may diverge in UI layer, frontend flavors, suite/module availability, SSR site baselines, project assets, and generated outputs.
 - For Zova frontend analysis, do not default to generic Vue reinterpretation first. Read the code through Zova’s controller / bean / IoC architecture before mapping it to Vue concepts.
 - For Zova source-reading or Vue-vs-Zova explanation tasks, start from the frontend reading guides and source-reading map in `cabloy-docs/frontend/` before doing framework-neutral reinterpretation.
+- In Zova page routes, any route with dynamic `params` must define `route.name`; do not rely on unnamed path-keyed routes for typed `$params`, and regenerate page metadata after route changes.
 - For frontend async state that affects rendering or interaction across consumers, prefer model-owned `$useStateData(...)` over controller-managed fetch/cache state.
 - Default to establishing such query state during render. Use `disableSuspenseOnInit: true` only for relatively stable query-backed state when you want to skip the init-time `query.suspense()` kick; it does not prevent query creation, fetches, or hydration-time rendering. If strict readiness is needed later, wait explicitly at the interaction boundary.
 - In SSR, keep server HTML and the client's hydration-time initial render equivalent. When server rendering intentionally omits private, cookie-unavailable, or browser-only state, keep the same neutral shell or placeholder through hydration and defer its query/load/render branch to an explicit post-hydration, admission, mounted, or interaction boundary.

package/cabloy-docs/.vitepress/config.mjs

@@ -92,6 +92,11 @@ const fullstackGroups = [
       },
       { text: 'Framework Performance', link: '/fullstack/framework-performance' },
       { text: 'Vona + Zova Integration', link: '/fullstack/vona-zova-integration' },
+      { text: 'A-Pay Payment Suite', link: '/fullstack/a-pay-payment-suite' },
+      {
+        text: 'Payment Provider Sandbox Configuration',
+        link: '/fullstack/payment-sandbox-configuration',
+      },
       { text: 'Contract Loop Playbook', link: '/fullstack/contract-loop-playbook' },
       {
         text: 'Admin Resource and Web Self-Service',
@@ -254,6 +259,7 @@ export default defineConfig({
             { text: 'Upload Guide', link: '/backend/upload-guide' },
             { text: 'Image Guide', link: '/backend/image-guide' },
             { text: 'File Guide', link: '/backend/file-guide' },
+            { text: 'Markdown Guide', link: '/backend/markdown-guide' },
             { text: 'Mail Guide', link: '/backend/mail-guide' },
             { text: 'Serialization Guide', link: '/backend/serialization-guide' },
           ],
@@ -445,6 +451,7 @@ export default defineConfig({
             { text: 'Form Layout Guide', link: '/frontend/form-layout-guide' },
             { text: 'Image Guide', link: '/frontend/image-guide' },
             { text: 'File Guide', link: '/frontend/file-guide' },
+            { text: 'Markdown Guide', link: '/frontend/markdown-guide' },
             {
               text: 'Zova Form Under the Hood',
               link: '/frontend/zova-form-under-the-hood',

package/cabloy-docs/backend/markdown-guide.md

@@ -0,0 +1,189 @@
+# Backend Markdown Guide
+
+This guide documents the Vona `a-markdown` module in Cabloy Basic. It is a small server-side rendering and sanitization module, not a content-management product or an HTTP API by itself.
+
+Use this page together with:
+
+- [Frontend Markdown Guide](/frontend/markdown-guide)
+- [Validation Guide](/backend/validation-guide)
+- [Serialization Guide](/backend/serialization-guide)
+
+## What `a-markdown` provides
+
+The module registers one global Vona bean:
+
+```typescript
+this.bean.markdown.renderHtml(markdown);
+```
+
+The public method is:
+
+```typescript
+renderHtml(markdown?: string): string
+```
+
+Its behavior is intentionally narrow:
+
+- execution is synchronous;
+- the return type is always `string`;
+- missing, empty, or whitespace-only input returns `''`;
+- non-empty input is parsed, rendered to HTML, and sanitized;
+- parsing and rendering errors are not swallowed by a local fallback.
+
+The module itself has no HTTP routes, controllers, DTOs, entities, database tables, migrations, locale resources, runtime configuration, or business persistence policy. A business module decides whether to store Markdown, store a derived HTML projection, return one of those values to each consumer, or delete an empty content record.
+
+For example, Commerce Catalog treats blank Markdown as absent product content and deletes its content record. That is a catalog service decision; `renderHtml()` only returns an empty string for blank input.
+
+## Rendering pipeline
+
+`BeanMarkdown.renderHtml()` follows this sequence:
+
+```text
+Markdown input
+  → MarkdownManager.parse(...)
+  → Tiptap static renderer
+  → sanitize-html with the module policy
+  → sanitized HTML string
+```
+
+The parser and static renderer are initialized once at module load. The configured extension set is:
+
+- `Markdown`
+- `StarterKit`
+- `TaskList`
+- nested `TaskItem`
+- `Image`
+- `TableKit`
+- `Highlight`
+
+The Markdown manager enables GitHub-flavored Markdown and uses two-space indentation:
+
+```typescript
+const markdownManager = new MarkdownManager({
+  extensions,
+  markedOptions: { gfm: true },
+  indentation: { style: 'space', size: 2 },
+});
+```
+
+The module therefore supports the configured rich-text structures—such as headings, emphasis, lists, task lists, code, images, and tables—but it should not be documented as preserving arbitrary raw HTML or every feature of a general Markdown product. The extension list and sanitizer allowlist are the current contract.
+
+## Sanitization is part of the API contract
+
+The rendered HTML is always passed through a fixed `sanitize-html` policy. The policy is defined in source and is not a runtime configuration option that callers can replace or extend.
+
+### Allowed document structures
+
+The allowlist retains the structures needed by the configured rich-text output:
+
+- document blocks: `p`, `br`, `hr`, `div`;
+- headings: `h1` through `h6`;
+- text marks: `em`, `strong`, `del`, `s`;
+- links: `a`;
+- lists and quotes: `ol`, `ul`, `li`, `blockquote`;
+- code: `code`, `pre`;
+- images: `img`;
+- task-list support: `input`, `label`, `span`;
+- tables: `table`, `thead`, `tbody`, `tr`, `th`, `td`.
+
+Scripts, iframes, style attributes, event-handler attributes, and other non-allowlisted elements are removed rather than preserved as arbitrary HTML.
+
+### Allowed attributes and classes
+
+Only the following attribute groups are retained:
+
+- links: `href`, `rel`, `target`, `title`;
+- code: `class`;
+- images: `alt`, `height`, `src`, `title`, `width`;
+- task inputs: `checked`, `disabled`, `type`;
+- task list items: `data-type`, `data-checked`;
+- task list containers: `data-type`;
+- spans: `class`.
+
+Class values are restricted by tag:
+
+- code classes must match `language-*`;
+- span classes must match `hljs-*`.
+
+Arbitrary classes and inline CSS do not become part of the output contract.
+
+### URL policy
+
+The sanitizer applies scheme checks to `href` and `src`:
+
+- links allow `http`, `https`, and `mailto`;
+- images allow only `http` and `https`;
+- protocol-relative URLs are disabled;
+- unsupported schemes such as `javascript:` do not survive as active link or image attributes.
+
+This is a content-safety rule, not an authorization rule. It does not decide whether a user may publish content, whether an external image is acceptable for privacy or availability reasons, or which CSP a consuming application should deploy.
+
+### Transformations
+
+The sanitizer also normalizes selected rendered elements:
+
+- every surviving anchor receives `rel="noopener noreferrer"`;
+- a checkbox input keeps its checked state when present but is always forced to `disabled="disabled"`;
+- a non-checkbox `input` is converted to an attribute-free `span`;
+- a task `li` keeps `data-type="taskItem"` only when valid, and keeps `data-checked` only when it is exactly `true` or `false`;
+- a task `ul` keeps `data-type="taskList"` only when valid;
+- unrelated attributes on task list elements are discarded.
+
+Task checkboxes are therefore presentation elements, not interactive controls.
+
+## The authoritative server projection pattern
+
+Commerce Catalog demonstrates the recommended source/projection boundary for a business resource:
+
+1. An Admin form submits `descriptionMarkdown`.
+2. The product service trims the Markdown.
+3. The service calls `this.bean.markdown.renderHtml(markdown)`.
+4. The service persists the Markdown source and generated HTML projection together.
+5. The Admin DTO returns the editable Markdown to the editor.
+6. The public detail DTO returns `descriptionHtml` without the editable Markdown.
+7. The Web page passes that server-derived HTML to `ZMarkdownHtml`.
+
+The core service operation is equivalent to:
+
+```typescript
+const markdown = descriptionMarkdown?.trim();
+if (!markdown) {
+  // The business module decides whether to remove empty content.
+  return;
+}
+
+const descriptionHtml = this.bean.markdown.renderHtml(markdown);
+await productContent.save({
+  descriptionMarkdown: markdown,
+  descriptionHtml,
+});
+```
+
+The actual Commerce Catalog service uses a row-locking lookup and either updates or inserts its content record. Its important security property is that it does not trust a caller-supplied `descriptionHtml`; it derives the value from Markdown on the server.
+
+The integration tests verify that:
+
+- headings, strong text, tables, code, images, and nested task lists are rendered;
+- task inputs are disabled;
+- `javascript:` links are not retained;
+- a submitted forged value such as `<script>forged</script>` is ignored in favor of newly rendered HTML;
+- blank Markdown removes the product content record in that business module;
+- the public detail exposes HTML while the Admin form receives Markdown.
+
+Every create, update, import, migration/backfill, or other write path that can change Markdown must apply the same server-side projection rule. Rendering only in one Admin endpoint leaves other write paths able to create stale or unsafe derived HTML.
+
+## Adopting Markdown in another module
+
+Use this checklist when adding Markdown-backed content:
+
+1. Decide whether the resource needs only Markdown or both Markdown and a derived HTML projection.
+2. Keep Markdown as the editable/source field.
+3. Call `this.bean.markdown.renderHtml(...)` on every authoritative write path.
+4. Define a business policy for blank Markdown; do not assume `renderHtml('')` deletes records.
+5. Expose the source and projection separately according to the consumer's authority.
+6. Use `basic-markdown:formFieldMarkdown` for the Markdown form field.
+7. Use `ZMarkdownHtml` only for HTML produced by the trusted server rendering path.
+8. Add tests for blank values, invalid URL schemes, task-list output, derived HTML consistency, and forged output fields.
+9. Treat external-image policy, CSP, authorization, and content lifecycle cleanup as application concerns beyond this renderer.
+
+The matching frontend component and SSR behavior are documented in [Frontend Markdown Guide](/frontend/markdown-guide).

package/cabloy-docs/frontend/component-guide.md

@@ -103,6 +103,12 @@ class RenderPageCounter {
 }
 ```
 
+## `controllerRef` and internal companion access
+
+`controllerRef` is a consumer-side mechanism: it exposes this component's Controller instance to the component's caller. It is distinct from the internal companion-member access used by a split Controller, Render, and Style implementation.
+
+Inside one component, use direct `this.member` access for ordinary companion state, actions, and generated style classes. For the lookup order, shadowing rule, and cases that require explicit identity or interop access instead, see [Page Guide: Companion-member access](/frontend/page-guide#companion-member-access-in-a-split-page).
+
 ## Practical implications for component implementation
 
 When working on Zova components, do not automatically fall back to generic Vue component habits.

package/cabloy-docs/frontend/css-in-js-guide.md

@@ -56,6 +56,12 @@ A practical rule is:
 
 This is an organizational split, not a different styling engine. Zova still uses the same CSS-in-JS model; it simply gives larger pages and components a better place to hold their style concerns.
 
+### Style beans in a split Controller/Render/Style component
+
+A Style Bean owns generated class setup. It can directly read its companion Controller's state through `this.member`; a Render Bean can consume the Style Bean's generated class through the same direct access surface, for example `this.cClass`. Keep Style class names distinct from Controller state and actions, because a same-name member on the current bean takes precedence.
+
+For the complete lookup order and the boundary between ordinary companion access and explicit bean identity/interop access, see [Page Guide: Companion-member access](/frontend/page-guide#companion-member-access-in-a-split-page).
+
 ## Shared/global styles with `@Css()` and `$cssBase`
 
 Not every style should stay local.