@xh/hoist 86.1.0 → 86.3.0

package/desktop/cmp/tab/Tabs.scss

@@ -36,9 +36,36 @@
     }
   }
 
+  // Generic tab defaults - orientation-specific blocks below layer on top of these.
+  .bp6-tab {
+    color: var(--xh-tab-text-color);
+
+    &[aria-disabled='true'] {
+      color: var(--xh-tab-disabled-text-color);
+    }
+
+    // Tooltip
+    .bp6-popover-target {
+      width: 100%;
+    }
+  }
+
+  // Active/hover color override
+  .bp6-tab[aria-selected='true'],
+  .bp6-tab:not([aria-disabled='true']):hover {
+    .xh-tab-switcher__tab {
+      color: var(--xh-tab-active-text-color);
+    }
+  }
+
   &--top {
     padding-left: var(--xh-pad-px);
     max-width: 100%;
+
+    // Active indicator sits on the bottom edge of the tab, adjacent to the content below.
+    .bp6-tab[aria-selected='true'] {
+      box-shadow: inset 0 -3px 0 var(--xh-tab-active-text-color);
+    }
   }
 
   &--bottom {
@@ -56,6 +83,8 @@
   &--right {
     flex-direction: column;
     max-height: 100%;
+    min-width: var(--xh-tab-switcher-vertical-min-width);
+    padding: var(--xh-tab-switcher-vertical-padding);
 
     // Make overflow button full width
     .bp6-popover-target {
@@ -65,6 +94,49 @@
         width: 100%;
       }
     }
+
+    // Modern vertical rail: rounded, padded items with a muted resting color, a clear hover
+    // affordance, and a filled active "pill". Fully driven off the --xh-tab-switcher-vertical-*
+    // tokens so it stays light/dark-theme safe and is easily customized or disabled per-app.
+    .bp6-tab {
+      margin-bottom: var(--xh-tab-switcher-vertical-item-gap);
+      padding: var(--xh-tab-switcher-vertical-item-padding);
+      border-radius: var(--xh-tab-switcher-vertical-item-border-radius);
+      color: var(--xh-tab-switcher-vertical-item-text-color);
+      font-weight: var(--xh-tab-switcher-vertical-item-font-weight);
+      transition:
+        background-color 0.15s ease,
+        color 0.15s ease,
+        box-shadow 0.15s ease;
+    }
+
+    .bp6-tab:not([aria-disabled='true']):hover {
+      background-color: var(--xh-tab-switcher-vertical-item-hover-bg);
+    }
+
+    .bp6-tab[aria-selected='true'] {
+      background-color: var(--xh-tab-switcher-vertical-item-active-bg);
+      font-weight: var(--xh-tab-switcher-vertical-item-active-font-weight);
+    }
+
+    // Hover + active labels take the active/intent text color, re-applied to both the tab and its
+    // inner label so it overrides the muted resting color set on the item above.
+    .bp6-tab[aria-selected='true'],
+    .bp6-tab:not([aria-disabled='true']):hover {
+      color: var(--xh-tab-switcher-vertical-item-active-text-color);
+
+      .xh-tab-switcher__tab {
+        color: var(--xh-tab-switcher-vertical-item-active-text-color);
+      }
+    }
+  }
+
+  &--left {
+    border-right: var(--xh-tab-switcher-vertical-border);
+  }
+
+  &--right {
+    border-left: var(--xh-tab-switcher-vertical-border);
   }
 
   &__tab {
@@ -104,29 +176,4 @@
       min-height: 20px !important;
     }
   }
-
-  .bp6-tab {
-    color: var(--xh-tab-text-color);
-
-    &[aria-disabled='true'] {
-      color: var(--xh-tab-disabled-text-color);
-    }
-
-    // Tooltip
-    .bp6-popover-target {
-      width: 100%;
-    }
-  }
-
-  // Active/hover color override
-  .bp6-tab[aria-selected='true'],
-  .bp6-tab:not([aria-disabled='true']):hover {
-    .xh-tab-switcher__tab {
-      color: var(--xh-tab-active-text-color);
-    }
-  }
-
-  .bp6-tab[aria-selected='true'] {
-    box-shadow: inset 0 -3px 0 var(--xh-tab-active-text-color);
-  }
 }

package/docs/routing.md

@@ -150,10 +150,12 @@ numeric-only parameters). See the
 ### Conditional Route Exclusion
 
 Routes support an `omit` property (a Hoist extension, not part of Router5) that allows
-declarative exclusion of routes at registration time. This is useful for role-gated sections:
+declarative exclusion of routes at registration time. This is useful for role-gated sections.
+`getRoutes()` returns `HoistRoute[]` - Hoist's `Route` type extended with the optional `omit` key -
+so the property type-checks without any cast:
 
 ```typescript
-override getRoutes() {
+override getRoutes(): HoistRoute[] {
     return [{
         name: 'default',
         path: '/app',

package/docs/upgrade-notes/v86-upgrade-notes.md

@@ -221,7 +221,21 @@ grep -rn "fileChooser\|FileChooser" client-app/src/
 | `minSize` (prop) | `FileChooserModel` config `minFileSize` |
 | `enableMulti` / `enableAddMulti` (props) | `FileChooserModel` config `maxFiles` (set `1` for single-file; omit for unlimited) |
 | `showFileGrid` (prop) | Removed - default display is a grid; customize via the `fileDisplay` content prop |
-| `targetText` (prop) | `FileChooserModel` config `emptyDisplayPrompt` (+ `emptyDisplayHint`), or replace via the `emptyDisplay` content prop |
+| `targetText` (prop) | **Preferred:** `FileChooserModel` config `emptyDisplayPrompt` (+ `emptyDisplayHint`). Use the `emptyDisplay` content prop only for a fully custom layout. |
+
+> **`emptyDisplay` and `fileDisplay` switch on file *presence*; v85's `targetText` did not.**
+> In v85 the drop target that rendered `targetText` was **always visible** - even with files
+> selected - and the file grid (if enabled) sat alongside it. v86 has no always-visible text slot:
+> `emptyDisplay` renders **only when no files are selected**, and `fileDisplay` (defaulting to the
+> grid/card) renders **only when files are present**. There is therefore no mechanical mapping for a
+> `targetText` - you must decide which presence-state its content belonged to:
+> - A drop prompt ("Drag and drop files here") is empty-state content - set it as
+>   `emptyDisplayPrompt` (a plain string, preferred - keeps Hoist's icon, styling, and the
+>   auto-generated constraints hint). When files exist, the grid/`fileDisplay` takes over.
+> - A message that only makes sense once a file is chosen (e.g. "Ready to upload") belongs in
+>   `fileDisplay`, which replaces the default grid - so set it only if you don't need that grid.
+> - If your `targetText` varied on an **app flag** rather than on file presence, preserve that flag
+>   *inside* the slot you choose - do not let the empty/file switch silently stand in for it.
 
 Before (v85 - config as component props, model takes no args):
 ```typescript
@@ -283,17 +297,68 @@ constructor() {
 }
 ```
 
-**If your `targetText` was a React element** (not a plain string) - e.g. a `placeholder(...)` or a
-custom layout - move it to the `emptyDisplay` content prop rather than `emptyDisplayPrompt`.
-`emptyDisplayPrompt` accepts a `ReactNode` and is fine for a styled message, but `emptyDisplay`
-replaces the entire empty-state content, which is the closer match for a fully custom `targetText`:
+**Prefer the styled text prompt over rebuilding the UI.** Most `targetText` values were a string or
+a simple `placeholder(Icon.upload(), '...')` - which is exactly what the default empty display
+already renders. Map these to `emptyDisplayPrompt` (a plain string on the model), optionally with
+`emptyDisplayHint`: you keep Hoist's upload icon, styling, and the auto-generated summary of accepted
+types and size/count limits. This holds even when `targetText` was a `placeholder(...)` element -
+collapse it back to the prompt string rather than reaching for a content prop.
 
 ```typescript
-// Before (v85)
+// Before (v85) - a plain-text or simple-placeholder targetText
+fileChooser({model, targetText: 'Drop loan docs here'})
 fileChooser({model, targetText: placeholder(Icon.upload(), 'Drop loan docs here')})
 
-// After (v86)
-fileChooser({model, emptyDisplay: placeholder(Icon.upload(), 'Drop loan docs here')})
+// After (v86) - map targetText to a styled prompt on the model; icon, styling, and the constraints
+// hint come for free, and the component render needs no change
+new FileChooserModel({emptyDisplayPrompt: 'Drop loan docs here'});
+```
+
+Reserve the `emptyDisplay` / `fileDisplay` content props for layouts the prompt/hint genuinely can't
+express. Note they are **not** interchangeable targets for a `targetText`: `emptyDisplay` renders
+only when empty and `fileDisplay` only when files are present, so content meant for the
+file-populated state must go to `fileDisplay` - never `emptyDisplay`.
+
+**If your `targetText` was conditional** - a ternary or computed expression - work out what the
+condition actually tracked before migrating, because v86 already switches content on file presence.
+
+In the common case the condition tracked *file presence* (a flag toggled as files are added and
+removed). v86's built-in switch replaces it directly: the no-file prompt becomes `emptyDisplayPrompt`
+and the flag is dropped. The plain drop text needs no content prop at all - only the custom "ready"
+affirmation, meant for the file-populated state, uses `fileDisplay` (which overrides the default
+grid). `enableMulti` moves to `maxFiles` on the model:
+
+```typescript
+// Before (v85) - targetText always visible, toggled by a presence-derived flag
+fileChooser({
+    model,
+    enableMulti: !singleDoc,
+    targetText: hasFile
+        ? placeholder(Icon.check({intent: 'success'}), 'Ready to upload')
+        : placeholder(Icon.upload(), 'Drag and drop files here')
+})
+
+// After (v86) - the presence switch is built in, so the flag is no longer needed
+this.chooserModel = new FileChooserModel({
+    maxFiles: singleDoc ? 1 : null,
+    emptyDisplayPrompt: 'Drag and drop files here'
+});
+fileChooser({
+    model: this.chooserModel,
+    fileDisplay: placeholder(Icon.check({intent: 'success'}), 'Ready to upload')
+})
+```
+
+The trap is a condition that is **independent of file presence** (e.g. an "uploads open" flag). Its
+branches are *not* an empty/file pair, so splitting them across `emptyDisplay` / `fileDisplay` would
+drop the condition and silently re-key the content onto presence. Keep such a flag *inside* the slot
+its content belongs to - here, still on the styled prompt:
+
+```typescript
+// independent flag - preserved on the styled prompt (model config), not mapped onto presence
+new FileChooserModel({
+    emptyDisplayPrompt: acceptingUploads ? 'Drag and drop files here' : 'Uploads are closed'
+});
 ```
 
 ### 4. Remove Deleted Mobile `DateInput` Props

package/format/FormatNumber.ts

@@ -14,6 +14,7 @@ import {
     isNil,
     isNumber,
     isString,
+    isUndefined,
     round
 } from 'lodash';
 import Numbro from 'numbro';
@@ -78,8 +79,9 @@ export interface NumberFormatOptions extends Omit<FormatOptions<number>, 'toolti
     omitFourDigitComma?: boolean;
 
     /**
-     * Desired number of decimal places, or 'auto' (default) to adjust the displayed precision
-     * automatically based on the scale of the value.
+     * Desired number of decimal places, 'auto' (default) to adjust the displayed precision
+     * automatically based on the scale of the value, or null for full, unrestricted precision
+     * (capped at the max supported precision, with trailing zeros trimmed).
      */
     precision?: Precision;
 
@@ -118,15 +120,23 @@ export interface NumberFormatOptions extends Omit<FormatOptions<number>, 'toolti
      *
      * e.g. `{precision:4, zeroPad:2}` will format `1.2` → "1.20" and `1.234` → "1.234"
      *
-     * Default is true if a fixed precision is set, false if precision is 'auto'.
+     * Default is true if a fixed precision is set, false if precision is 'auto' or null (full).
      */
     zeroPad?: ZeroPad;
 }
 
 export interface QuantityFormatOptions extends NumberFormatOptions {
+    /** True to compact values \>= 1 million into units of millions (m). Default true. */
     useMillions?: boolean;
 
+    /** True to compact values \>= 1 billion into units of billions (b). Default true. */
     useBillions?: boolean;
+
+    /**
+     * True to compact to m/b units only when no precision is lost, else render the full value.
+     * Default false.
+     */
+    lossless?: boolean;
 }
 
 /** Config for pos/neg/neutral color classes. */
@@ -175,9 +185,16 @@ export function fmtNumber(v: number, opts?: NumberFormatOptions): ReactNode {
     } = opts ?? ({} as NumberFormatOptions);
     if (isInvalidInput(v)) return nullDisplay;
 
-    // Ensure any non-int precision is treated as 'auto', use to default zeroPad.
-    if (!isInteger(precision)) precision = 'auto';
-    if (isNil(zeroPad)) zeroPad = precision != 'auto';
+    // Resolve precision: null means full precision, other non-integers (e.g. undefined) mean 'auto'.
+    const fullPrecision = precision === null;
+    if (fullPrecision) {
+        precision = MAX_NUMERIC_PRECISION;
+    } else if (!isInteger(precision)) {
+        precision = 'auto';
+    }
+
+    // Default zeroPad to pad only for a fixed precision - 'auto' and full precision trim zeros.
+    if (isNil(zeroPad)) zeroPad = precision != 'auto' && !fullPrecision;
 
     formatConfig =
         formatConfig || buildFormatConfig(v, precision, zeroPad, withCommas, omitFourDigitComma);
@@ -271,20 +288,40 @@ export function fmtQuantity(v: number, opts?: QuantityFormatOptions) {
     saveOriginal(v, opts);
     if (isInvalidInput(v)) return fmtNumber(v, opts);
 
-    const lessThanM = Math.abs(v) < MILLION,
-        lessThanB = Math.abs(v) < BILLION;
-
     defaults(opts, {
         ledger: true,
         label: true,
-        precision: lessThanM ? 0 : 2,
         useMillions: true,
-        useBillions: true
+        useBillions: true,
+        lossless: false
     });
 
-    if (lessThanM || !opts.useMillions) return fmtNumber(v, opts);
-    if (lessThanB || !opts.useBillions) return fmtMillions(v, opts);
-    return fmtBillions(v, opts);
+    const absV = Math.abs(v),
+        lessM = absV < MILLION,
+        lessB = absV < BILLION,
+        targetPrecision = opts.precision ?? (lessM ? 0 : 2);
+
+    // Compute scaling, if any (Lossless flag may preclude).
+    let scale = !lessB && opts.useBillions ? BILLION : !lessM && opts.useMillions ? MILLION : null;
+    if (scale && opts.lossless) {
+        const precision = parsePrecision(absV / scale, targetPrecision),
+            lossy = v % (scale / 10 ** precision) !== 0;
+        if (lossy) scale = null;
+    }
+
+    // Resolve render precision (unless the caller set one).
+    if (isUndefined(opts.precision)) {
+        opts.precision = opts.lossless ? null : targetPrecision;
+    }
+
+    switch (scale) {
+        case BILLION:
+            return fmtBillions(v, opts);
+        case MILLION:
+            return fmtMillions(v, opts);
+        default:
+            return fmtNumber(v, opts);
+    }
 }
 
 /**
@@ -462,6 +499,23 @@ function calcStyleFromColorSpec(v: number, colorSpec: ColorSpec | boolean): CSSP
     return !isString(possibleStyles) ? possibleStyles : {};
 }
 
+/**
+ * Resolve a precisionSpec to a concrete number of decimal places. A fixed precision is used as-is
+ * (capped at max), while 'auto' is derived from the scale of the value.
+ */
+function parsePrecision(v: number, precisionSpec: Precision): number {
+    // Fixed precision - use requested, capped at max.
+    if (precisionSpec !== 'auto') return Math.min(precisionSpec, MAX_NUMERIC_PRECISION);
+
+    // 'auto' - derive from the scale of the value.
+    const absVal = Math.abs(v);
+    if (absVal === 0) return 2;
+    if (absVal < 0.01) return 6;
+    if (absVal < 100) return 4;
+    if (absVal < 10000) return 2;
+    return 0;
+}
+
 function buildFormatConfig(
     v: number,
     precisionSpec: Precision,
@@ -472,24 +526,7 @@ function buildFormatConfig(
     const absVal = Math.abs(v),
         config: Numbro.Format = {};
 
-    let precision: number;
-    if (precisionSpec === 'auto') {
-        // Auto-precision - base on scale of number
-        if (absVal === 0) {
-            precision = 2;
-        } else if (absVal < 0.01) {
-            precision = 6;
-        } else if (absVal < 100) {
-            precision = 4;
-        } else if (absVal < 10000) {
-            precision = 2;
-        } else {
-            precision = 0;
-        }
-    } else {
-        // Fixed precision - use requested, capped at max.
-        precision = precisionSpec < MAX_NUMERIC_PRECISION ? precisionSpec : MAX_NUMERIC_PRECISION;
-    }
+    const precision = parsePrecision(v, precisionSpec);
 
     // If zeroPad gte precision, treat as `true` to pad out to (but not beyond) full precision.
     // We don't support applying some precision (rounding) then padding out zeroes after that.

package/icon/Icon.scss

@@ -0,0 +1,13 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2026 Extremely Heavy Industries Inc.
+ */
+
+// FA v7 sizes icons via the `--fa-width` custom property (default 1.25em) rather than the old
+// `fa-fw` class. The placeholder is a plain div, so it reads the same property to stay aligned
+// with sibling icons under any width override, falling back to FA's default when unset.
+.xh-icon--placeholder {
+  width: var(--fa-width, 1.25em);
+}

package/icon/Icon.ts

@@ -15,6 +15,7 @@ import {ReactElement} from 'react';
 import {iconCmp} from './impl/IconCmp';
 import {enhanceFaClasses, iconHtml} from './impl/IconHtml';
 import {SetRequired} from 'type-fest';
+import './Icon.scss';
 
 export interface IconProps extends HoistProps, Partial<Omit<FontAwesomeIconProps, 'ref'>> {
     /** Name of the icon in FontAwesome. */
@@ -932,9 +933,9 @@ export const Icon = {
     },
 
     /**
-     * Returns an empty div with FA sizing classes applied. Can be used to take up room in a layout
-     * where an icon might otherwise go - e.g. to align a series of menu items, where some items do
-     * not have an icon but others do.
+     * Returns an empty div sized to occupy the width of a standard icon. Can be used to take up
+     * room in a layout where an icon might otherwise go - e.g. to align a series of menu items,
+     * where some items do not have an icon but others do.
      */
     placeholder(opts?: IconProps): any {
         const {size, asHtml = false} = opts ?? {},

package/icon/impl/IconHtml.ts

@@ -32,5 +32,5 @@ export function iconHtml({
 }
 
 export function enhanceFaClasses(className: string, size: string) {
-    return classNames(className, 'fa-fw', 'xh-icon', isString(size) ? `fa-${size}` : null);
+    return classNames(className, 'xh-icon', isString(size) ? `fa-${size}` : null);
 }

package/kit/react-dropzone/index.ts

@@ -8,5 +8,6 @@ import {elementFactory} from '@xh/hoist/core';
 import Dropzone from 'react-dropzone';
 
 export {Dropzone};
+export {ErrorCode} from 'react-dropzone';
 export type {Accept, FileRejection, FileWithPath} from 'react-dropzone';
 export const dropzone = elementFactory(Dropzone);

package/mcp/README.md

@@ -725,6 +725,18 @@ The `resolveDocPath()` utility in `util/paths.ts` validates that resolved paths
 repository root. It rejects paths containing `..` segments. Always use this function when resolving
 file paths from external input.
 
+### Path Separators (Cross-Platform)
+
+ts-morph's `SourceFile.getFilePath()` always returns **forward-slash** paths on every platform
+(e.g. `D:/hoist-react/cmp/grid/GridModel.ts` on Windows), whereas `resolveRepoRoot()` returns a
+native path from Node's `path` module -- **backslash-separated** on Windows (`D:\hoist-react`).
+Comparing or slicing one against the other (e.g. `filePath.startsWith(repoRoot + '/')`) silently
+fails on Windows, filtering out every source file and yielding an empty symbol index. When
+comparing against or slicing a ts-morph path, use `resolveRepoRootPosix()` (and `toPosixPath()` for
+any incoming file-path argument) from `util/paths.ts` rather than `resolveRepoRoot()`. Filesystem
+access that stays within Node's `path`/`fs` APIs (e.g. the doc registry, the index cache) can keep
+using `resolveRepoRoot()`, since those are separator-consistent on both sides.
+
 ### Registry Sync
 
 The doc registry is hardcoded, not filesystem-scanned. When documentation files are added or

package/mcp/data/ts-registry.spec.ts

@@ -0,0 +1,156 @@
+/**
+ * Test harness for the TypeScript symbol registry's cross-platform path handling.
+ * Run with:
+ *   npx tsx mcp/data/ts-registry.spec.ts
+ *
+ * The hoist-react repo has no general test framework configured, so this script
+ * is a self-contained, exit-coded driver. It guards the path normalization the
+ * symbol index depends on: ts-morph's `getFilePath()` reports forward-slash paths
+ * on every platform, while Node's `path` reports backslashes on Windows. The two
+ * must be reconciled (to POSIX form) before comparison - a regression silently
+ * filters out every source file and empties the entire symbol index on Windows.
+ * See the "Path Separators (Cross-Platform)" pitfall in mcp/README.md.
+ *
+ * Two layers:
+ *  - Synthetic path-helper cases (`toPosixPath`, `resolveRepoRootPosix`,
+ *    `toRelativePath`, and the exact index-guard comparison) - these simulate a
+ *    Windows path explicitly, so they are meaningful on any host OS, including
+ *    Linux/macOS CI.
+ *  - Live index integration - exercises `searchSymbols` / `getSymbolDetail` /
+ *    `getMembers` against the real hoist-react sources to prove symbols resolve
+ *    end-to-end (and that repo-relative `--file` disambiguation works).
+ *
+ * Run after every change to ts-registry.ts, index-cache.ts, or util/paths.ts.
+ */
+import {resolveRepoRoot, resolveRepoRootPosix, toPosixPath} from '../util/paths.js';
+import {toRelativePath} from '../formatters/typescript.js';
+import {searchSymbols, getSymbolDetail, getMembers} from './ts-registry.js';
+
+// Suppress info logs during test run; we only want test output. (Warns still print.)
+process.env.HOIST_MCP_QUIET = '1';
+
+//---------------------------------------------------------------------
+// Minimal assertion helpers (match the exit-coded style of the sibling
+// doc-id-resolver.spec.ts).
+//---------------------------------------------------------------------
+
+let passed = 0;
+let failed = 0;
+const failures: string[] = [];
+
+function ok(label: string, cond: boolean, detail?: string): void {
+    if (cond) {
+        passed++;
+        console.log(`  PASS  ${label}`);
+    } else {
+        failed++;
+        failures.push(detail ? `${label} -- ${detail}` : label);
+        console.log(`  FAIL  ${label}`);
+        if (detail) console.log(`        ${detail}`);
+    }
+}
+
+function eq(label: string, actual: unknown, expected: unknown): void {
+    ok(
+        label,
+        actual === expected,
+        `got ${JSON.stringify(actual)}, expected ${JSON.stringify(expected)}`
+    );
+}
+
+//---------------------------------------------------------------------
+// Synthetic path-helper cases (host-OS-independent).
+//---------------------------------------------------------------------
+
+console.log('toPosixPath cases:');
+eq(
+    'converts backslashes',
+    toPosixPath('D:\\hoist-react\\core\\XH.ts'),
+    'D:/hoist-react/core/XH.ts'
+);
+eq('leaves forward slashes untouched', toPosixPath('/repo/core/XH.ts'), '/repo/core/XH.ts');
+eq('normalizes mixed separators', toPosixPath('a\\b/c\\d'), 'a/b/c/d');
+eq('is idempotent', toPosixPath(toPosixPath('D:\\a\\b')), 'D:/a/b');
+
+console.log('\nresolveRepoRootPosix cases:');
+const rootPosix = resolveRepoRootPosix();
+ok('has no backslashes', !rootPosix.includes('\\'), `got "${rootPosix}"`);
+eq('equals toPosixPath(resolveRepoRoot())', rootPosix, toPosixPath(resolveRepoRoot()));
+
+console.log('\nIndex-guard regression cases (simulated Windows paths):');
+// The exact scenario that broke: on Windows, resolveRepoRoot() yields a
+// backslash path while ts-morph yields forward slashes. Assert the naive guard
+// fails and the POSIX-normalized guard succeeds - regardless of the host OS.
+const winRootNative = 'D:\\hoist-react'; // what resolveRepoRoot() returns on Windows
+const winFile = 'D:/hoist-react/cmp/grid/GridModel.ts'; // what ts-morph getFilePath() returns on Windows
+ok(
+    'naive backslash-root comparison fails (the original bug)',
+    !winFile.startsWith(winRootNative + '/')
+);
+ok(
+    'posix-normalized root comparison succeeds (the fix)',
+    winFile.startsWith(toPosixPath(winRootNative) + '/')
+);
+eq(
+    'relative slice under posix root is correct',
+    winFile.slice(toPosixPath(winRootNative).length + 1),
+    'cmp/grid/GridModel.ts'
+);
+
+console.log('\ntoRelativePath cases:');
+const sampleRel = 'cmp/grid/GridModel.ts';
+eq('strips a posix absolute path', toRelativePath(`${rootPosix}/${sampleRel}`), sampleRel);
+// A backslash absolute path (same root) must still strip AND normalize to posix.
+const backslashAbs = `${rootPosix.replace(/\//g, '\\')}\\cmp\\grid\\GridModel.ts`;
+eq('strips + normalizes a backslash absolute path', toRelativePath(backslashAbs), sampleRel);
+
+//---------------------------------------------------------------------
+// Live index integration (needs the real hoist-react sources; builds or
+// loads the cached index on first query).
+//---------------------------------------------------------------------
+
+console.log('\nLive index cases:');
+
+const results = await searchSymbols('GridModel', {limit: 5});
+const gm = results.find(r => r.name === 'GridModel' && r.kind === 'class');
+ok('searchSymbols("GridModel") finds the class', !!gm, `got ${results.length} results`);
+if (gm) {
+    eq('GridModel resolves to cmp/grid/GridModel.ts', toRelativePath(gm.filePath), sampleRel);
+    eq('GridModel sourcePackage is cmp/grid', gm.sourcePackage, 'cmp/grid');
+}
+
+const detail = await getSymbolDetail('GridModel');
+ok(
+    'getSymbolDetail("GridModel") resolves',
+    !!detail && detail.kind === 'class',
+    `got ${JSON.stringify(detail && {name: detail.name, kind: detail.kind})}`
+);
+
+const members = await getMembers('GridModel');
+ok(
+    'getMembers("GridModel") returns members',
+    !!members && members.members.length > 0,
+    `count=${members?.members.length ?? 0}`
+);
+
+// --file disambiguation (the secondary Windows bug): a repo-relative path passed
+// to findIndexEntry must resolve to the matching entry. `View` exists in both
+// cmp/viewmanager and data/cube; the path selects the data/cube one.
+const view = await getSymbolDetail('View', 'data/cube/View.ts');
+ok(
+    'getSymbolDetail("View", "data/cube/View.ts") disambiguates by repo-relative path',
+    !!view && toRelativePath(view.filePath) === 'data/cube/View.ts',
+    `relPath=${view ? toRelativePath(view.filePath) : 'null'}`
+);
+
+//---------------------------------------------------------------------
+// Tally
+//---------------------------------------------------------------------
+
+console.log(`\nTotal: ${passed} passed, ${failed} failed.`);
+
+if (failed > 0) {
+    console.log('\nFailure details:');
+    for (const f of failures) console.log(`  - ${f}`);
+    process.exit(1);
+}