@jskit-ai/agent-docs 0.1.116 → 0.1.117

package/guide/agent/app-setup/a-more-interesting-shell.md

@@ -675,6 +675,19 @@ The closed presentation is adaptive and uses Vuetify's Material navigation
 components. On compact/mobile layouts the temporary drawer closes completely.
 On medium and expanded layouts it collapses to a navigation rail by default,
 so primary navigation remains visible. Opening it restores the full drawer.
+Escape and outside dismissal close only the compact temporary drawer and return
+focus to the shell navigation toggle. They do not collapse permanent desktop
+navigation.
+
+The open drawer is content-aware by default. After the visible semantic
+placements and fonts settle, `ShellLayout` measures the rendered labels and
+keeps the drawer edge approximately 10 CSS pixels beyond the widest label. It
+remeasures when placements, localization, fonts, the active surface, or the
+window layout change, and clamps unusually long labels to a safe range. The
+closed desktop rail remains 80 CSS pixels wide by default, with every icon and
+its Material selected-state indicator centred in the rail. Rail tooltips use
+one explicit opaque theme color pair and open on pointer hover or keyboard
+focus.
 
 The app-owned `ShellLayout` can opt into a fully hidden wide drawer when the
 product has another discoverable navigation affordance:
@@ -688,6 +701,23 @@ product has another discoverable navigation affordance:
 The default is `desktop-drawer-closed-mode="rail"`. Prefer that Material 3
 pattern; do not imitate a rail with custom CSS or a second menu registry.
 
+Applications that need fixed product-specific dimensions can use the public
+width props instead of overriding Vuetify drawer CSS:
+
+```vue
+<ShellLayout :drawer-width="280" :rail-width="88">
+  <RouterView />
+</ShellLayout>
+```
+
+Omit `drawer-width` to retain content-aware sizing. Omit `rail-width` to retain
+the 80px Material navigation-rail default. Drawer overrides are clamped to
+120–360px and rail overrides to 48–160px so shell navigation cannot consume an
+unsafe share of the viewport or shrink below its touch targets. The app-owned
+`src/components/ShellLayout.vue` wrapper forwards these attributes to the
+package component, so an application does not need to copy or restyle the
+drawer implementation.
+
 `useShellErrorPresentationStore()` exposes the current banner, snackbar, and dialog presentation state behind `ShellErrorHost`.
 
 The simplest direct store usage looks like this:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.116",
+  "version": "0.1.117",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/placements.md

@@ -58,6 +58,9 @@ Runtime behavior:
 - Runtime resolves the component token as `entry.componentToken || variant.renderers[entry.kind]`.
 - Entries without a resolvable component token do not render.
 - `when()` receives placement context including `app`, `surface`, `target`, `layoutClass`, runtime context, local outlet context, and context contributors.
+- The standard `ShellLayout` sizes its open drawer from the widest currently visible placement label plus an approximately 10px logical-end gap. It remeasures after placement, locale, font, surface, and layout changes. Use the public `drawerWidth` prop only when a product needs a fixed width; do not add consumer `.v-navigation-drawer` overrides.
+- On medium and expanded layouts, closing the standard drawer produces an 80px navigation rail by default. Use `railWidth` to configure that width, or `desktopDrawerClosedMode="hidden"` only when another discoverable navigation surface exists.
+- The shell link renderers own rail centring, selected-state treatment, and opaque theme-aware tooltips. Applications should keep supplying the same semantic placement records rather than creating rail-only links or tooltip CSS.
 
 CLI and generators:
 

package/patterns/ui-testing.md

@@ -13,6 +13,7 @@ Rules:
 - Generator or package template UI changes must be checked at compact phone, tablet-ish medium, and expanded desktop widths.
 - For generated UI, check horizontal overflow, clipped or invisible text, duplicate navigation, and broken route placement at every standard viewport. On compact screens, also check generated-screen tap targets under 48 px; medium and expanded layouts may use their documented denser controls.
 - Apps with `shell-web` installed should start from `tests/e2e/adaptive-shell.spec.ts` and extend it with feature-specific assertions.
+- The package helper reads the shell's rendered `data-layout` contract, waits for drawer transitions without fixed sleeps, verifies compact Escape/outside dismissal, checks content-aware drawer fit, and measures rail icon centring against the configured width. Do not replace it with viewport-name assumptions or immediate animation-time geometry reads.
 - Generated `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`. Do not copy base-URL, web-server, or storage-state logic into app tests.
 - Use relative paths such as `page.goto("/home")`. The shared config owns the browser base URL.
 - A managed runner supplies `PLAYWRIGHT_BASE_URL`. When it is set, JSKIT does not start another app server.

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

@@ -65,6 +65,17 @@ Local functions
 Exports
 - None
 Local functions
+- `attachShellListeners()`
+- `detachShellListeners()`
+- `handleDrawerOpenChange(open)`
+- `handleLayoutClassChange(compact)`
+- `handleShellKeydown(event)`
+- `focusNavigationToggle()`
+- `initializeDrawerMeasurement()`
+- `resolveNavigationDrawerElement()`
+- `scheduleDrawerWidthMeasurement()`
+- `measureDrawerContentWidth()`
+- `measureRenderedText(element)`
 - `handlePullPointerDown(event)`
 - `handleDrawerVisibilityChange(open)`
 - `handlePullPointerMove(event)`
@@ -91,6 +102,10 @@ Local functions
 Exports
 - None
 
+### `src/client/components/ShellNavigationTooltip.vue`
+Exports
+- None
+
 ### `src/client/components/ShellOutlet.vue`
 Exports
 - None
@@ -412,6 +427,19 @@ Exports
 - `resolveShellDrawerPresentation({ compact = false, open = false, desktopClosedMode = "rail" } = {})`
 - `resolveShellDrawerToggleLabel({ compact = false, open = false } = {})`
 
+### `src/client/support/drawerWidth.js`
+Exports
+- `DEFAULT_SHELL_DRAWER_WIDTH`
+- `DEFAULT_SHELL_RAIL_WIDTH`
+- `MAXIMUM_SHELL_DRAWER_WIDTH`
+- `MINIMUM_SHELL_DRAWER_WIDTH`
+- `SHELL_DRAWER_LABEL_END_GAP`
+- `normalizeShellDrawerWidth(value, fallback = DEFAULT_SHELL_DRAWER_WIDTH)`
+- `normalizeShellRailWidth(value, fallback = DEFAULT_SHELL_RAIL_WIDTH)`
+- `resolveContentAwareDrawerWidth(measurements = [], { endGap = SHELL_DRAWER_LABEL_END_GAP, minimum = MINIMUM_SHELL_DRAWER_WIDTH, maximum = MAXIMUM_SHELL_DRAWER_WIDTH, fallback = DEFAULT_SHELL_DRAWER_WIDTH } = {})`
+Local functions
+- `clampNumber(value, minimum, maximum)`
+
 ### `src/client/support/menuLinkTarget.js`
 Exports
 - `normalizeMenuLinkPathname(pathname = "")`
@@ -422,6 +450,10 @@ Local functions
 - `isRelativeMenuLinkTarget(target = "")`
 - `surfaceRequiresWorkspaceFromPlacementContext(contextValue = null, surfaceId = "")`
 
+### `src/client/support/navigationLinkKeyboard.js`
+Exports
+- `activateShellNavigationLinkOnSpace(event)`
+
 ### `src/client/support/routeTransitionKey.js`
 Exports
 - `resolveShellRouteTransitionKey({ routePathKey = "", routeTransitionName = "", surfaceId = "" } = {})`
@@ -512,3 +544,24 @@ Exports
 ### `package.descriptor.mjs`
 Exports
 - None
+
+### fixtures
+
+### `fixtures/adaptive-shell/src/App.vue`
+Exports
+- None
+
+### `fixtures/adaptive-shell/src/main.js`
+Exports
+- None
+Local functions
+- `createSurfacePlacement(surface, order, label, suffix)`
+- `createSurfacePlacements(surface)`
+
+### `fixtures/adaptive-shell/src/ScreenPage.vue`
+Exports
+- None
+
+### `fixtures/adaptive-shell/vite.config.mjs`
+Exports
+- None

package/skills/jskit/references/ui-operations.md

@@ -47,6 +47,11 @@ navigation as a rail. Use `desktopDrawerClosedMode="hidden"` only when another
 discoverable navigation affordance exists. Do not create a second drawer/menu
 registry or imitate the rail with CSS.
 
+The open drawer tracks its widest visible label plus about 10px. The 80px
+desktop rail centres complete 48px targets and opaque theme-owned tooltips.
+Set `ShellLayout` `drawerWidth` or `railWidth` only for a fixed product width;
+the app wrapper forwards both. Never override `.v-navigation-drawer` in an app.
+
 ## Browser verification
 
 Exercise user-facing changes with Playwright at compact, medium, and expanded