@jskit-ai/agent-docs 0.1.273 → 0.1.275

package/reference/autogen/packages/shell-web.md

@@ -80,12 +80,25 @@ Exports
 ### `src/client/components/ShellLayout.vue`
 Exports
 - None
+Local functions
+- `updateScrolled()`
+- `goUp()`
+
+### `src/client/components/ShellListDetail.vue`
+Exports
+- None
+Local functions
+- `releasePane()`
 
 ### `src/client/components/ShellMenuLinkItem.vue`
 Exports
 - None
 
-### `src/client/components/ShellNavigationTooltip.vue`
+### `src/client/components/ShellNavigationItem.vue`
+Exports
+- None
+
+### `src/client/components/ShellNavigationScope.vue`
 Exports
 - None
 
@@ -100,6 +113,16 @@ Local functions
 Exports
 - None
 
+### `src/client/components/ShellPageAction.vue`
+Exports
+- None
+Local functions
+- `handleClick(event)`
+
+### `src/client/components/ShellPageActions.vue`
+Exports
+- None
+
 ### `src/client/components/ShellRouteTransition.vue`
 Exports
 - None
@@ -120,7 +143,7 @@ Exports
 
 ### `src/client/composables/useShellDrawer.js`
 Exports
-- `useShellDrawer({ props, isCompactLayout, navigationToggle, layoutState })`
+- `useShellDrawer({ props, modalLayout, viewportWidth, navigationToggle, layoutState })`
 Local functions
 - `navigationDrawerElement()`
 
@@ -142,6 +165,10 @@ Exports
 - `shellNavigationLinkProps`
 - `useShellNavigationLink(props)`
 
+### `src/client/composables/useShellPageTitle.js`
+Exports
+- `useShellPageTitle(title)`
+
 ### `src/client/composables/useShellPullToRefresh.js`
 Exports
 - `useShellPullToRefresh({ enabled, refreshRuntime })`
@@ -152,6 +179,10 @@ Local functions
 Exports
 - `useShellRouteTransition(props)`
 
+### `src/client/composables/useShellWindowSizeClass.js`
+Exports
+- `useShellWindowSizeClass()`
+
 ### `src/client/error/index.js`
 Exports
 - `createDefaultErrorPolicy`
@@ -244,7 +275,15 @@ Exports
 - `ShellMenuLinkItem`
 - `ShellSurfaceAwareMenuLinkItem`
 - `ShellTabLinkItem`
+- `ShellPageActions`
+- `ShellPageAction`
+- `ShellListDetail`
 - `useShellLayoutState`
+- `useShellPageTitle`
+- `useShellWindowSizeClass`
+- `useShellNavigation`
+- `leaveApp`
+- `reloadAppPage`
 - `useShellLayoutStore`
 - `useShellErrorPresentationStore`
 - `SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY`
@@ -265,6 +304,11 @@ Local functions
 - `normalizePathname(value = "")`
 - `resolveSurfaceSwitchIdFromLabel(label = "")`
 
+### `src/client/navigation/documentNavigation.js`
+Exports
+- `leaveApp(url)`
+- `reloadAppPage(target)`
+
 ### `src/client/navigation/linkResolver.js`
 Exports
 - `resolveShellLinkPath({ context = null, surface = "", explicitTo = "", relativePath = "/", surfaceRelativePath = "", params = {}, strictParams = true } = {})`
@@ -273,6 +317,18 @@ Local functions
 - `materializeSurfaceRouteBase(routeBaseTemplate = "/", { params = {}, strictParams = true, surface = "" } = {})`
 - `resolveSurfaceBasePath(context = null, surface = "", { params = {}, strictParams = true } = {})`
 
+### `src/client/navigation/shellNavigationRuntime.js`
+Exports
+- `PAGE_TITLE_ID`
+- `SHELL_NAVIGATION_RUNTIME_KEY`
+- `TRAIL_STATE_KEY`
+- `createShellNavigationRuntime({ router })`
+- `resolvePageParent(matched)`
+- `resolvePageTitle(matched)`
+Local functions
+- `normalizeTrail(value)`
+- `cssAttributeValue(value)`
+
 ### `src/client/navigation/usePaths.js`
 Exports
 - `usePaths({ routeContext = useSurfaceRouteContext() } = {})`
@@ -282,6 +338,15 @@ Local functions
 - `resolveDefaultSurfaceIdFromPlacementContext(placementContext = null)`
 - `resolveRouteParams(baseParams = {}, overrideParams = null)`
 
+### `src/client/navigation/useShellNavigation.js`
+Exports
+- `NO_SHELL_NAVIGATION_RUNTIME`
+- `useShellNavigation()`
+- `useShellNavigationRuntime()`
+Local functions
+- `resolvedNothing()`
+- `releaseNothing()`
+
 ### `src/client/navigation/useSurfaceRouteContext.js`
 Exports
 - `useSurfaceRouteContext()`
@@ -459,14 +524,15 @@ Exports
 Exports
 - `DESKTOP_DRAWER_CLOSED_MODES`
 - `normalizeDesktopDrawerClosedMode(value = "rail")`
-- `resolveShellDrawerPresentation({ compact = false, open = false, desktopClosedMode = "rail" } = {})`
-- `resolveShellDrawerToggleLabel({ compact = false, open = false } = {})`
+- `resolveShellDrawerPresentation({ modal = false, open = false, desktopClosedMode = "rail" } = {})`
+- `resolveShellDrawerToggleLabel({ modal = false, open = false } = {})`
 
 ### `src/client/support/drawerWidth.js`
 Exports
 - `DEFAULT_SHELL_DRAWER_WIDTH`
 - `DEFAULT_SHELL_NAVIGATION_ITEM_SPACING`
 - `DEFAULT_SHELL_RAIL_WIDTH`
+- `MATERIAL_DRAWER_WIDTH`
 - `MAXIMUM_SHELL_DRAWER_WIDTH`
 - `MINIMUM_SHELL_DRAWER_WIDTH`
 - `measureDrawerContentWidth(drawerElement, navigationItemSpacing)`
@@ -474,6 +540,7 @@ Exports
 - `normalizeShellNavigationItemSpacing(value, fallback = DEFAULT_SHELL_NAVIGATION_ITEM_SPACING)`
 - `normalizeShellRailWidth(value, fallback = DEFAULT_SHELL_RAIL_WIDTH)`
 - `resolveContentAwareDrawerWidth(measurements = [], { endGap = DEFAULT_SHELL_NAVIGATION_ITEM_SPACING, minimum = MINIMUM_SHELL_DRAWER_WIDTH, maximum = MAXIMUM_SHELL_DRAWER_WIDTH, fallback = DEFAULT_SHELL_DRAWER_WIDTH } = {})`
+- `resolveMaterialDrawerWidth({ modal = false, viewportWidth = Number.POSITIVE_INFINITY } = {})`
 Local functions
 - `clampNumber(value, minimum, maximum)`
 - `measureRenderedText(element)`
@@ -498,6 +565,17 @@ Local functions
 Exports
 - `activateShellNavigationLinkOnSpace(event)`
 
+### `src/client/support/navigationPresentation.js`
+Exports
+- `NO_SHELL_NAVIGATION_PRESENTATION`
+- `NO_SHELL_PAGE_ACTIONS_TARGET`
+- `NO_VUETIFY_ICONS`
+- `SHELL_NAVIGATION_PRESENTATION_KEY`
+- `SHELL_PAGE_ACTIONS_ID`
+- `SHELL_PAGE_ACTIONS_TARGET_KEY`
+- `VUETIFY_ICONS_KEY`
+- `filledIconAlias(icon, aliases)`
+
 ### `src/client/support/primaryNavigation.js`
 Exports
 - `normalizeComparablePathname(value = "")`
@@ -523,7 +601,15 @@ Exports
 
 ### `src/client/support/shellLayoutClass.js`
 Exports
-- `resolveShellLayoutClass(displayName = "", viewportWidth = pageViewportWidth())`
+- `resolveShellLayoutClass(viewportWidth = pageViewportWidth())`
+
+### `src/client/support/windowSizeClass.js`
+Exports
+- `EXPANDED_MIN_WIDTH`
+- `LARGE_MIN_WIDTH`
+- `MEDIUM_MIN_WIDTH`
+- `WINDOW_SIZE_CLASSES`
+- `resolveWindowSizeClass(width)`
 
 ### `src/client/types.js`
 Exports
@@ -552,11 +638,33 @@ Exports
 Local functions
 - `createSurfacePlacement(surface, order, label, suffix)`
 - `createSurfacePlacements(surface)`
+- `refuseBlockedRecord(to)`
+
+### `fixtures/adaptive-shell/src/RecordListPage.vue`
+Exports
+- None
+
+### `fixtures/adaptive-shell/src/RecordPage.vue`
+Exports
+- None
+
+### `fixtures/adaptive-shell/src/records.js`
+Exports
+- `records`
 
 ### `fixtures/adaptive-shell/src/ScreenPage.vue`
 Exports
 - None
 
+### `fixtures/adaptive-shell/src/SettingsPage.vue`
+Exports
+- None
+
+### `fixtures/adaptive-shell/src/theme/index.js`
+Exports
+- `theme`
+- `adminTheme`
+
 ### `fixtures/adaptive-shell/vite.config.mjs`
 Exports
 - None
@@ -575,6 +683,10 @@ Exports
 Exports
 - None
 
+### `patterns/application-shell/example/expected-existing/src/views/NotFound.vue`
+Exports
+- None
+
 ### `patterns/application-shell/example/src/App.vue`
 Exports
 - None
@@ -615,10 +727,6 @@ Exports
 Exports
 - None
 
-### `patterns/application-shell/example/src/pages/home/settings/index.vue`
-Exports
-- None
-
 ### `patterns/application-shell/example/src/placement.js`
 Exports
 - `addPlacement`
@@ -629,6 +737,10 @@ Exports
 - `addPlacementTopology(value = {})`
 - `default`
 
+### `patterns/application-shell/example/src/views/NotFound.vue`
+Exports
+- None
+
 ### `patterns/page-and-placement/example/packages/main/src/client/providers/MainClientProvider.js`
 Exports
 - `MainClientProvider`

package/reference/autogen/tooling/jskit-catalog.md

@@ -67,9 +67,90 @@ Exports
 - `usage()`
 Local functions
 - `parseI18nArgs(options, positionals)`
+- `parseMaterial3Args(options, positionals)`
+- `runMaterial3({ projectRoot, paths })`
 - `runI18n({ subcommand, locale, projectRoot })`
 - `readCatalog()`
 
+### `scripts/material3-source.mjs`
+Exports
+- `HEX_COLOUR`
+- `blankCssComments(source)`
+- `blankHtmlComments(source)`
+- `blankJsComments(source)`
+- `kebab(name)`
+- `lineIndex(text)`
+- `readDeclarations(css, offset)`
+- `readExceptions(source)`
+- `readInlineDeclarations(text, offset)`
+- `readTags(template)`
+- `splitVue(source)`
+Local functions
+- `blank(text)`
+- `blankMatches(source, pattern)`
+- `findBlocks(source, tag)`
+- `readAttributes(text, offset)`
+
+### `scripts/material3.mjs`
+Exports
+- `MATERIAL3_RULES`
+- `checkMaterial3({ projectRoot = process.cwd(), paths = [], navigationOnly = false } = {})`
+- `formatMaterial3Report(result)`
+- `formatNavigationReport(result)`
+Local functions
+- `hexPattern()`
+- `quotedHex()`
+- `isNavigationRule(rule)`
+- `isSkippedDirectory(name)`
+- `isSourceFile(relativePath)`
+- `walk(projectRoot, directory, files)`
+- `collectFiles(projectRoot, paths)`
+- `createReporter(file, source, { navigationOnly = false } = {})`
+- `checkCode(code, offset, { report, themed })`
+- `checkScript(code, offset, context)`
+- `checkCss(css, offset, context)`
+- `checkDeclaration(declaration, context)`
+- `attribute(tag, name)`
+- `checkTemplate(template, context)`
+- `checkAttribute(tag, entry, context)`
+- `checkSurface(tag, report)`
+- `checkButtonSize(tag, report)`
+- `checkFile(file, source, context)`
+- `readProjectManifest(projectRoot)`
+- `usesShell(manifest)`
+- `checkDarkScheme(projectRoot, checkedFiles, wholeApp)`
+- `formatFindings(result)`
+
+### `scripts/navigation.mjs`
+Exports
+- `NAVIGATION_RULES`
+- `checkBackControl(tag, report)`
+- `checkLinkAttribute(tag, entry, report)`
+- `checkNavigationCode(code, offset, report)`
+- `checkPageParents({ root, appFiles, pageFiles, report })`
+- `checkScriptBackNames(code, offset, report)`
+- `isInAppPath(value)`
+- `isPageFile(file)`
+Local functions
+- `compact(text)`
+- `isPlacementLink(code, offset)`
+- `attribute(tag, name)`
+- `visibleText(inner)`
+- `isBackTag(tag)`
+- `looksLikeBack(tag)`
+- `balancedFrom(text, start, open = "{", close = "}")`
+- `enclosingObject(text, offset)`
+- `stringValue(text, key)`
+- `readMainNavigation(sources)`
+- `normalisePath(value)`
+- `routeOf(file)`
+- `routePattern(route)`
+- `readSurfaces(configSource, pageRoutes)`
+- `surfaceOf(route, surfaces)`
+- `routeDeclarations(source)`
+- `readPage(file, source)`
+- `pageKey(file)`
+
 ### `scripts/pattern-assets.mjs`
 Exports
 - `PATTERN_DOCUMENT_NAME`

package/reference/autogen/tooling/testUtils.md

@@ -27,3 +27,10 @@ Exports
 - `createFakeFastifyPolicyRuntime({ csrfHandler = passCsrfProtection } = {})`
 Local functions
 - `passCsrfProtection(_request, _reply, done)`
+
+### `visualBaseline.mjs`
+Exports
+- `expectMaterialBaseline(page, { directory, name, probes })`
+- `readMaterialStyles(page, probes)`
+Local functions
+- `comparePixels(page, actual, expected)`

package/skills/jskit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jskit
-description: Build, extend, troubleshoot, review, deslop, and verify JSKIT apps using its public framework APIs, package-owned source patterns, runtime capabilities, surfaces, placements, CRUDs, verification conventions, and Vue/Vuetify Material 3 UI contract. Use for every JSKIT UI creation, modification, review, or cleanup task.
+description: Build, extend, troubleshoot, review, deslop, and verify JSKIT apps using its public framework APIs, package-owned source patterns, runtime capabilities, surfaces, placements, CRUDs, verification conventions, and Vue/Vuetify Material 3 UI contract, including UI passes over a task's changes, a section, or the whole app. Use for every JSKIT UI creation, modification, review, cleanup, or UI pass task.
 ---
 
 # JSKIT
@@ -56,6 +56,8 @@ manifests, migrations, tests, and runtime behaviour are the evidence.
      [UI operations](references/ui-operations.md).
    - For every Vue/Vuetify UI creation, modification, review, or deslop task,
      also read [Material 3](references/material-3.md) completely before acting.
+   - For a UI pass (the changes, a section, or the whole app), also read
+     [UI pass](references/ui-pass.md) completely.
 
 These are complete operational references required by this skill. Do not load
 irrelevant references or other docs.
@@ -90,9 +92,11 @@ only when required. Use only a fresh disposable development database for
 schema work—never valuable data. For UI, respect surface/placements, compact
 layout, all operational states, permissions/ownership, and browser
 verification.
-Check every page for meaningful Back navigation: previous page by default,
-with justified omissions or explicitly named fixed destinations. UI operations
-has navigation seams, placement and direct-entry fallback.
+Navigation is a MUST that plain `jskit check` enforces (Material 3,
+Navigation and Up): the shell owns the Up arrow and the trail; every inner page
+declares its parent as route meta `jskit.parent`; every inner link goes through
+JSKIT navigation; never write back logic, a "Back to X" control,
+`router.back()`, `history.back()` or `window.location` navigation.
 
 ## Caller-owned verification
 
@@ -107,8 +111,9 @@ For review-only work, report without editing. Check dead or duplicated code,
 accidental abstraction, incomplete states, missed high-level JSKIT seams,
 invalid ownership or migration choices, UI quality, and verification. Server
 code follows typed features, client code client features; `npm run lint` is
-clean. Run the Material 3 audit for affected UI, Back included; a hardcoded
-parent link is not previous-page navigation. Findings first by severity and file.
+clean. Run the Material 3 audit for affected UI, navigation first, plain
+`jskit check`, and `jskit check m3` on the affected files. Findings first by
+severity and file.
 
 ## Verify
 

package/skills/jskit/references/heuristics/INDEX.md

@@ -34,7 +34,7 @@ How to use it:
   - [client-requests.md](./client-requests.md)
 - playwright, browser test, e2e, ui verification, baseline test, authenticated ui test, test auth, dev login as, dev auth bypass
   - [ui-testing.md](./ui-testing.md)
-- UI contract, design contract, navigation roles, Back button, previous page, history, hardcoded destination, Deslop, density, placeholder copy, card shells, shared CRUD screens, row actions, synthetic rows, detail slots
+- UI contract, design contract, navigation roles, Up arrow, Back button, declared parent, jskit.parent, in-app trail, history.back, hand-built links, jskit check, Deslop, density, placeholder copy, card shells, shared CRUD screens, row actions, synthetic rows, detail slots
   - [ui-contract.md](./ui-contract.md)
 - filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
   - [filters.md](./filters.md)

package/skills/jskit/references/heuristics/ui-contract.md

@@ -13,11 +13,13 @@ and action UI.
   overflow.
 - Compact interactive targets are at least 48 CSS pixels.
 - Navigation uses semantic placements and explicit navigation roles.
-- Check every page for Back to the previous page unless returning makes no
-  product sense. Use the existing navigation owner; fixed destinations are
-  deliberate, explicitly labelled exceptions. Follow the
-  [Back navigation contract](../ui-operations.md#back-navigation)
-  for history, direct-entry fallback, retained context, and consistent placement.
+- MUST, enforced by plain `jskit check`: every inner page declares its parent
+  (route meta `jskit.parent`) and gets one Up arrow in the top app bar from the
+  shell; it returns to the in-app origin, or to the parent on direct entry.
+  Main-menu destinations show none. No "Back to X" controls, no back logic, no
+  `router.back()`/`history.back()`/`window.location`, no hand-built in-app
+  links. Follow
+  [Navigation and Up](../material-3.md#navigation-and-up).
 - Pages do not stack decorative cards inside structural cards.
 - Pages do not include a header, title block, welcome heading, or standalone
   heading copy unless the user explicitly requests one.
@@ -57,8 +59,9 @@ it as a closed sheet and wider layouts as a closed side panel.
 
 - test skeleton, empty, loaded, local error, retry, and mutation feedback states
 - navigate away and back with warm query cache, including browser back/forward
-- during review or Deslop, audit Back's presence or justified omission, leading
-  position, label, and actual destination; verify two origins and direct entry
+- during review, Deslop or a UI pass, audit Up: a sideways origin returns
+  there, chains unwind, direct entry reaches the declared parent, and main-menu
+  destinations show no arrow
 - exercise compact, medium, and expanded viewports
 - verify accessible names, keyboard operation, target size, and no overflow
 - assert that no spinner or layout-shifting transient error banner appears

package/skills/jskit/references/heuristics/ui-testing.md

@@ -22,9 +22,11 @@ Rules:
 - Use relative paths such as `page.goto("/home")`. The shared config owns the browser base URL.
 - After clicking a client-side navigation control, wait for its destination
   with `await expect(page).toHaveURL(...)` before reloading. Awaiting the click
-  alone does not wait for Vue Router to complete. Contextual Back tests must
-  reach the form before reload, then assert the original list URL; direct entry
-  checks the configured fallback separately. Do not replace this wait with sleeps.
+  alone does not wait for Vue Router to complete. Up tests reach a page
+  through in-app links (one of them sideways), then press
+  `pressShellBack(page)` (`@jskit-ai/shell-web/test/shellNavigation`) and
+  assert that each Up returns to its origin in order; a direct `page.goto()`
+  asserts the declared parent. Do not replace this wait with sleeps.
 - A managed runner supplies `PLAYWRIGHT_BASE_URL`. When it is set, JSKIT does not start another app server.
 - Otherwise the config starts the app on `PLAYWRIGHT_PORT`, 4173 by default. A runner that shares a machine between runs sets a free port for each run; with one fixed port, a second run would wait for it or reuse another run's server.
 - A managed runner may supply an authenticated context through `PLAYWRIGHT_STORAGE_STATE`. Treat that file as a temporary secret: do not commit it, print it, or retain it after the run.