cabloy 5.1.165 → 5.1.167

package/.cabloy-version

@@ -1 +1 @@
-5.1.165
+5.1.167

package/.claude/scheduled_tasks.lock

@@ -1 +1 @@
-{"sessionId":"ca46c3da-f068-490d-8585-52645b0c5e32","pid":48025,"procStart":"Wed Sep  9 23:18:11 2026","acquiredAt":1789174622732}
+{"sessionId":"4dc366c1-f1a5-45c5-a2e1-5c89e5694587","pid":67516,"procStart":"Sat Sep 12 08:03:56 2026","acquiredAt":1789284193785}

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

@@ -165,6 +165,7 @@ Check whether the feature needs:
 
 - page route review
 - params/query schema alignment
+- for numeric Zova page params and query fields, use `z.number()` and rely on the Cabloy/Zova route/query parse adapter; do not generalize this behavior to standalone Zod parsing or add manual coercion without a separate input-boundary requirement
 - effective layout, authentication, and SSR-profile default resolution
 - static-name and ordinary-alias exception review
 - alias or guard review

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 5.1.167
+
+### Features
+
+- Add routed dialog support.
+- Add update capabilities.
+- Add bean general generation support.
+
+### Improvements
+
+- Update resource handling.
+- Update Zod documentation.
+
+## 5.1.166
+
+### Improvements
+
+- Refresh the Zova lockfile and update the Vona Zova Core patch.
+
 ## 5.1.165
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.165",
+  "version": "5.1.167",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/repo-docs/frontend/page-params-guide.md

@@ -26,7 +26,7 @@ export const ControllerPageCounterSchemaParams = z.object({
 
 This is more than a type annotation.
 
-Because route params arrive as strings at the URL level, the schema is also where Zova’s `z` wrapper can coerce the route value into the typed value that the page controller wants to consume.
+Route params arrive as strings at the URL level. On Zova's route/query parsing path, the Cabloy Zod query adapter converts a numeric value before the `z.number()` validation runs, so a successful `$params.id` value is a number. Use `z.number()` for numeric page params; `z.coerce.number()` is normally redundant here. For the exact scope and nil/error semantics, see [Zova route/query number parsing](./zod-guide#zova-routequery-number-parsing).
 
 ## Route record requirements
 

package/repo-docs/frontend/page-query-guide.md

@@ -31,6 +31,12 @@ export const ControllerPageCounterSchemaQuery = z.object({
 
 This matters because query parsing becomes typed and framework-aware instead of stringly-typed ad hoc access.
 
+## Numeric query values
+
+Query values are commonly strings at the URL boundary. On Zova's route/query parsing path, the Cabloy Zod query adapter converts a non-nil numeric value with `Number(...)` before ordinary `z.number()` validation. Use `z.number()` for numeric query fields such as `age`; when parsing succeeds, `this.$query.age` is a number.
+
+Invalid numeric text still fails number validation rather than silently producing a usable value. `z.coerce.number()` is normally redundant for Zova page query schemas, but may be appropriate at a different input boundary that does not use the Zova adapter. See [Zova route/query number parsing](/frontend/zod-guide#zova-routequery-number-parsing) for the adapter's nil semantics and scope.
+
 ## Use query values
 
 Representative pattern:

package/repo-docs/frontend/zod-guide.md

@@ -42,19 +42,21 @@ const user = z.object({
 
 This is the foundation used by typed page params and page query support.
 
-## Type coercion
+## Zova route/query number parsing
 
-One of the most important Zova enhancements is automatic coercion.
+Cabloy Basic pins `zod` in `zova/pnpm-workspace.yaml` to `npm:@cabloy/zod@4.3.8`. Zova's route/query parsing path uses the Cabloy Zod query adapter to prepare URL values before ordinary Zod validation.
 
-This matters because route params and query values often arrive as strings, while the page controller wants the final typed values.
-
-That is why schemas such as:
+For a non-nil numeric route or query value, the adapter applies `Number(value)` before `z.number()` validates it. Therefore, use `z.number()` for numeric fields in Zova page params and query schemas:
 
 ```typescript
-z.number();
+export const ControllerPageCounterSchemaQuery = z.object({
+  age: z.number().optional(),
+});
 ```
 
-can still support route-driven values more naturally than raw parsing code.
+When parsing succeeds, `this.$query.age` is a number. There is normally no need to add `z.coerce.number()` or a manual `Number(...)` conversion at this boundary.
+
+The adapter preserves its nil semantics: an empty string, `'undefined'`, or `'null'` is handled as an absent or null value rather than as an ordinary number. Invalid numeric text becomes `NaN` and still fails normal number validation. This behavior belongs to Zova's route/query parsing path; do not infer it for an arbitrary standalone `Zod.parse` call. Use `z.coerce.number()` when handling a different input boundary that does not use the Zova adapter.
 
 ## Boolean coercion
 

package/repo-e2e/specs/routed-dialog.spec.ts

@@ -0,0 +1,368 @@
+import type { Locator, Page } from '@playwright/test';
+
+import { expect, test } from '@playwright/test';
+
+declare global {
+  interface Window {
+    __routedDialogHydrationWarnings?: unknown[];
+  }
+}
+
+function collectPageErrors(page: Page) {
+  const errors: Error[] = [];
+  page.on('pageerror', error => {
+    errors.push(error);
+  });
+  return errors;
+}
+
+function collectConsoleErrors(page: Page) {
+  const errors: string[] = [];
+  page.on('console', message => {
+    const text = message.text();
+    if (
+      message.type() === 'error' ||
+      (message.type() === 'warning' && /hydration (node |children )?mismatch/i.test(text))
+    ) {
+      errors.push(`${message.type()}: ${text}`);
+    }
+  });
+  return errors;
+}
+
+async function installHydrationWarningProbe(page: Page) {
+  await page.addInitScript(() => {
+    const originalWarn = console.warn;
+    const warnings: unknown[] = [];
+    Object.defineProperty(window, '__routedDialogHydrationWarnings', {
+      configurable: true,
+      value: warnings,
+    });
+    console.warn = (...args: unknown[]) => {
+      try {
+        if (
+          args.some(
+            arg => typeof arg === 'string' && /Hydration (node|children) mismatch/.test(arg),
+          )
+        ) {
+          const node = args.find(arg => arg instanceof Node) as Node | undefined;
+          warnings.push({
+            args: args.map(arg => (typeof arg === 'string' ? arg : String(arg))),
+            node: node
+              ? {
+                  type: node.nodeType,
+                  value: node.nodeValue,
+                  parent: node.parentElement?.outerHTML.slice(0, 1000),
+                }
+              : undefined,
+          });
+        }
+      } finally {
+        originalWarn.apply(console, args as Parameters<typeof console.warn>);
+      }
+    };
+  });
+}
+
+async function getHydrationWarningProbe(page: Page) {
+  return await page.evaluate(() => window.__routedDialogHydrationWarnings ?? []);
+}
+
+function dialogByTitle(page: Page, dialog: 'A' | 'B') {
+  return page.getByRole('dialog').filter({
+    has: page.getByRole('heading', {
+      name: `Routed Dialog ${dialog}`,
+      exact: true,
+    }),
+  });
+}
+
+function routeRow(scope: Locator, name: string) {
+  return scope.locator('tbody tr').filter({ hasText: name }).last();
+}
+
+async function expectRouteValue(scope: Locator, name: string, value: string, type?: string) {
+  const row = routeRow(scope, name);
+  await expect(row.getByRole('cell').nth(1)).toHaveText(value);
+  if (type) {
+    await expect(row.getByRole('cell').nth(2)).toHaveText(type);
+  }
+}
+
+async function expectRoutePath(scope: Locator, pathname: string) {
+  const row = routeRow(scope, '$pageRoute.fullPath');
+  const fullPath = await row.getByRole('cell').nth(1).textContent();
+  expect(new URL(fullPath, 'http://e2e.invalid').pathname).toBe(pathname);
+}
+
+async function expectNoDialogLayout(dialog: Locator) {
+  await expect(dialog.locator('.drawer')).toHaveCount(0);
+}
+
+async function expectDialogMaxWidth(dialog: Locator, expected: string) {
+  await expect(dialog).toHaveCSS('max-width', expected);
+}
+
+async function getDialogTop(dialog: Locator) {
+  return Math.round((await dialog.boundingBox())?.y ?? -1);
+}
+
+async function expectDialogTop(dialog: Locator, expected: number) {
+  await expect.poll(() => getDialogTop(dialog)).toBe(expected);
+}
+
+async function openDemo(page: Page) {
+  const pageErrors = collectPageErrors(page);
+  const consoleErrors = collectConsoleErrors(page);
+  await installHydrationWarningProbe(page);
+  const response = await page.goto('/demo/basic/routedDialog', { waitUntil: 'load' });
+  expect(response?.ok()).toBeTruthy();
+  await expect(page.locator('html')).toHaveAttribute('data-zova-hydrated', 'web');
+  await expect(
+    page.getByRole('heading', { name: 'Routed Dialog Manual Validation', exact: true }),
+  ).toBeVisible();
+  const browserUrl = page.url();
+  await expect(
+    page
+      .getByRole('heading', { name: 'Main route sentinel', exact: true })
+      .locator('..')
+      .getByText(browserUrl, { exact: true }),
+  ).toBeVisible();
+  return { browserUrl, consoleErrors, pageErrors };
+}
+
+test(
+  'ATP-BASIC-ROUTED-DIALOG-01: a local memory router navigates without changing the browser route',
+  { tag: ['@web', '@flow'] },
+  async ({ page }) => {
+    const { browserUrl, consoleErrors, pageErrors } = await openDemo(page);
+
+    await page.getByRole('button', { name: 'Open A', exact: true }).click();
+    const dialogA = dialogByTitle(page, 'A');
+    await expect(dialogA).toHaveCount(1);
+    await expect(
+      dialogA.getByRole('heading', { name: 'Routed Dialog Entry', exact: true }),
+    ).toBeVisible();
+    await expectRoutePath(dialogA, '/demo/basic/routedDialogEntry');
+    await expectRouteValue(dialogA, '$query.dialog', 'A', 'string');
+    await expectRouteValue(dialogA, '$query.token', 'dialog-a-entry', 'string');
+    await expectRouteValue(dialogA, '$query.via', 'open', 'string');
+    await expectRouteValue(dialogA, '$query.step', '0', 'number');
+    await expect(dialogA.getByRole('button', { name: 'Back', exact: true })).toHaveCount(0);
+    await expectNoDialogLayout(dialogA);
+    expect(page.url()).toBe(browserUrl);
+
+    const entryTop = await getDialogTop(dialogA);
+    await dialogA.getByRole('button', { name: 'Local push to detail', exact: true }).click();
+    await expect(
+      dialogA.getByRole('heading', { name: 'Routed Dialog Detail', exact: true }),
+    ).toBeVisible();
+    await expectDialogTop(dialogA, entryTop);
+    await expectRoutePath(dialogA, '/demo/basic/routedDialogDetail/1');
+    await expectRouteValue(dialogA, '$params.id', '1', 'number');
+    await expectRouteValue(dialogA, '$query.token', 'dialog-a-entry-push', 'string');
+    await expectRouteValue(dialogA, '$query.via', 'page-push', 'string');
+    await expectRouteValue(dialogA, '$query.step', '1', 'number');
+    await expect(dialogA.getByRole('button', { name: 'Back', exact: true })).toBeVisible();
+    expect(page.url()).toBe(browserUrl);
+
+    await dialogA.getByRole('button', { name: 'Local replace next detail', exact: true }).click();
+    await expectRoutePath(dialogA, '/demo/basic/routedDialogDetail/11');
+    await expectRouteValue(dialogA, '$params.id', '11', 'number');
+    await expectRouteValue(dialogA, '$query.token', 'dialog-a-entry-push-replace', 'string');
+    await expectRouteValue(dialogA, '$query.via', 'detail-replace', 'string');
+    await expectRouteValue(dialogA, '$query.step', '11', 'number');
+    await expect(dialogA.getByRole('button', { name: 'Back', exact: true })).toBeVisible();
+    expect(page.url()).toBe(browserUrl);
+
+    await dialogA.getByRole('button', { name: 'Back', exact: true }).click();
+    await expect(
+      dialogA.getByRole('heading', { name: 'Routed Dialog Entry', exact: true }),
+    ).toBeVisible();
+    await expect(dialogA.getByRole('button', { name: 'Back', exact: true })).toHaveCount(0);
+    await expectRouteValue(dialogA, '$query.token', 'dialog-a-entry', 'string');
+    expect(page.url()).toBe(browserUrl);
+
+    await dialogA.getByRole('button', { name: 'Local push to detail', exact: true }).click();
+    await expect(
+      dialogA.getByRole('heading', { name: 'Routed Dialog Detail', exact: true }),
+    ).toBeVisible();
+    await expect(dialogA.getByRole('button', { name: 'Back', exact: true })).toBeVisible();
+    await dialogA.getByRole('button', { name: 'Local router.back', exact: true }).click();
+    await expect(
+      dialogA.getByRole('heading', { name: 'Routed Dialog Entry', exact: true }),
+    ).toBeVisible();
+    await expect(dialogA.getByRole('button', { name: 'Back', exact: true })).toHaveCount(0);
+    expect(page.url()).toBe(browserUrl);
+
+    await page.keyboard.press('Escape');
+    await expect(dialogA).toHaveCount(0);
+    expect(page.url()).toBe(browserUrl);
+    expect(pageErrors).toEqual([]);
+    expect(consoleErrors).toEqual([]);
+    expect(await getHydrationWarningProbe(page)).toEqual([]);
+  },
+);
+
+test(
+  'ATP-BASIC-ROUTED-DIALOG-02: routed-dialog handles push and replace locally',
+  { tag: ['@web', '@flow'] },
+  async ({ page }) => {
+    const { browserUrl, consoleErrors, pageErrors } = await openDemo(page);
+    const dialogA = dialogByTitle(page, 'A');
+
+    await page.getByRole('button', { name: 'Open A with handle.push', exact: true }).click();
+    await expect(
+      dialogA.getByRole('heading', { name: 'Routed Dialog Detail', exact: true }),
+    ).toBeVisible();
+    await expectRoutePath(dialogA, '/demo/basic/routedDialogDetail/101');
+    await expectRouteValue(dialogA, '$params.id', '101', 'number');
+    await expectRouteValue(dialogA, '$query.token', 'dialog-a-handle-push', 'string');
+    await expectRouteValue(dialogA, '$query.via', 'handle-push', 'string');
+    await expectRouteValue(dialogA, '$query.step', '1', 'number');
+    await expect(page.getByText('A: handle.push', { exact: true })).toBeVisible();
+    await expect(dialogA.getByRole('button', { name: 'Back', exact: true })).toBeVisible();
+    const handlePushTop = await getDialogTop(dialogA);
+    expect(page.url()).toBe(browserUrl);
+
+    await page.keyboard.press('Escape');
+    await expect(dialogA).toHaveCount(0);
+    expect(page.url()).toBe(browserUrl);
+
+    await page.getByRole('button', { name: 'Open A with handle.replace', exact: true }).click();
+    await expect(
+      dialogA.getByRole('heading', { name: 'Routed Dialog Detail', exact: true }),
+    ).toBeVisible();
+    await expectRoutePath(dialogA, '/demo/basic/routedDialogDetail/202');
+    await expectRouteValue(dialogA, '$params.id', '202', 'number');
+    await expectRouteValue(dialogA, '$query.token', 'dialog-a-handle-replace', 'string');
+    await expectRouteValue(dialogA, '$query.via', 'handle-replace', 'string');
+    await expectRouteValue(dialogA, '$query.step', '2', 'number');
+    await expect(page.getByText('A: handle.replace', { exact: true })).toBeVisible();
+    await expect(dialogA.getByRole('button', { name: 'Back', exact: true })).toHaveCount(0);
+    await expectDialogTop(dialogA, handlePushTop);
+    expect(page.url()).toBe(browserUrl);
+
+    await page.keyboard.press('Escape');
+    await expect(dialogA).toHaveCount(0);
+    expect(page.url()).toBe(browserUrl);
+    expect(pageErrors).toEqual([]);
+    expect(consoleErrors).toEqual([]);
+    expect(await getHydrationWarningProbe(page)).toEqual([]);
+  },
+);
+
+test(
+  'ATP-BASIC-ROUTED-DIALOG-04: routed dialogs apply responsive and scalar maximum widths',
+  { tag: ['@web', '@flow'] },
+  async ({ page }) => {
+    await page.setViewportSize({ width: 700, height: 900 });
+    const { browserUrl, consoleErrors, pageErrors } = await openDemo(page);
+    const dialogA = dialogByTitle(page, 'A');
+
+    await page.getByRole('button', { name: 'Open A', exact: true }).click();
+    await expect(dialogA).toHaveCount(1);
+    await expectDialogMaxWidth(dialogA, '640px');
+    await expectDialogTop(dialogA, 16);
+
+    await page.setViewportSize({ width: 900, height: 900 });
+    await expectDialogMaxWidth(dialogA, '768px');
+    await expectDialogTop(dialogA, 32);
+
+    await page.setViewportSize({ width: 1100, height: 900 });
+    await expectDialogMaxWidth(dialogA, '1024px');
+    await expectDialogTop(dialogA, 48);
+    await expectNoDialogLayout(dialogA);
+    expect(page.url()).toBe(browserUrl);
+
+    await page.keyboard.press('Escape');
+    await expect(dialogA).toHaveCount(0);
+
+    await page.getByRole('button', { name: 'Open A (720px width)', exact: true }).click();
+    await expect(dialogA).toHaveCount(1);
+    await expectDialogMaxWidth(dialogA, '720px');
+    await page.keyboard.press('Escape');
+    await expect(dialogA).toHaveCount(0);
+
+    await page.setViewportSize({ width: 900, height: 900 });
+    await page.getByRole('button', { name: 'Open A (md 800px width)', exact: true }).click();
+    await expect(dialogA).toHaveCount(1);
+    await expectDialogMaxWidth(dialogA, '800px');
+    await expectDialogTop(dialogA, 32);
+    await page.setViewportSize({ width: 700, height: 900 });
+    await expectDialogMaxWidth(dialogA, '640px');
+    await expectDialogTop(dialogA, 16);
+    await page.keyboard.press('Escape');
+    await expect(dialogA).toHaveCount(0);
+
+    await page.setViewportSize({ width: 900, height: 900 });
+    await page.getByRole('button', { name: 'Open A (80px top gutter)', exact: true }).click();
+    await expect(dialogA).toHaveCount(1);
+    await expectDialogTop(dialogA, 80);
+    await page.keyboard.press('Escape');
+    await expect(dialogA).toHaveCount(0);
+
+    await page.getByRole('button', { name: 'Open A (md 64px top gutter)', exact: true }).click();
+    await expect(dialogA).toHaveCount(1);
+    await expectDialogTop(dialogA, 64);
+    await page.setViewportSize({ width: 700, height: 900 });
+    await expectDialogTop(dialogA, 16);
+    expect(page.url()).toBe(browserUrl);
+
+    await page.keyboard.press('Escape');
+    await expect(dialogA).toHaveCount(0);
+    expect(pageErrors).toEqual([]);
+    expect(consoleErrors).toEqual([]);
+    expect(await getHydrationWarningProbe(page)).toEqual([]);
+  },
+);
+
+test(
+  'ATP-BASIC-ROUTED-DIALOG-03: concurrent dialogs keep isolated routes and close last-opened first',
+  { tag: ['@web', '@flow'] },
+  async ({ page }) => {
+    const { browserUrl, consoleErrors, pageErrors } = await openDemo(page);
+
+    await page.getByRole('button', { name: 'Open A and B', exact: true }).click();
+    const dialogA = dialogByTitle(page, 'A');
+    const dialogB = dialogByTitle(page, 'B');
+    await expect(dialogA).toHaveCount(1);
+    await expect(dialogB).toHaveCount(1);
+    await expect(
+      dialogA.getByRole('heading', { name: 'Routed Dialog Entry', exact: true }),
+    ).toBeVisible();
+    await expect(
+      dialogB.getByRole('heading', { name: 'Routed Dialog Entry', exact: true }),
+    ).toBeVisible();
+    await expectRouteValue(dialogA, '$query.token', 'dialog-a-entry', 'string');
+    await expectRouteValue(dialogB, '$query.token', 'dialog-b-entry', 'string');
+    await expect(dialogA.getByRole('button', { name: 'Back', exact: true })).toHaveCount(0);
+    await expect(dialogB.getByRole('button', { name: 'Back', exact: true })).toHaveCount(0);
+
+    await dialogB.getByRole('button', { name: 'Local push to detail', exact: true }).click();
+    await expect(
+      dialogB.getByRole('heading', { name: 'Routed Dialog Detail', exact: true }),
+    ).toBeVisible();
+    await expectRoutePath(dialogB, '/demo/basic/routedDialogDetail/1');
+    await expectRouteValue(dialogB, '$query.token', 'dialog-b-entry-push', 'string');
+    await expect(dialogB.getByRole('button', { name: 'Back', exact: true })).toBeVisible();
+    await expect(dialogA.getByRole('button', { name: 'Back', exact: true })).toHaveCount(0);
+    await expect(
+      dialogA.getByRole('heading', { name: 'Routed Dialog Entry', exact: true }),
+    ).toBeVisible();
+    await expectRouteValue(dialogA, '$query.token', 'dialog-a-entry', 'string');
+    expect(page.url()).toBe(browserUrl);
+
+    await page.keyboard.press('Escape');
+    await expect(dialogB).toHaveCount(0);
+    await expect(dialogA).toHaveCount(1);
+    expect(page.url()).toBe(browserUrl);
+
+    await page.keyboard.press('Escape');
+    await expect(dialogA).toHaveCount(0);
+    expect(page.url()).toBe(browserUrl);
+    expect(pageErrors).toEqual([]);
+    expect(consoleErrors).toEqual([]);
+    expect(await getHydrationWarningProbe(page)).toEqual([]);
+  },
+);