@sybilion/uilib 1.3.63 → 1.3.65

package/dist/esm/types/src/components/widgets/PerformanceChart/performanceChart.helpers.d.ts

@@ -21,14 +21,14 @@ export declare function isSpaghettiDriftPerHorizonLineId(id: number): boolean;
 /**
  * Converts `performance.model` / `performance.drift` per-horizon forecasts into synthetic
  * backtest-shaped entries: each line is [horizon_1[i], …, horizon_n[i]] as date→value points
- * (aligned by sorted key index per horizon).
+ * (aligned on the latest shared months per horizon).
  */
 export declare function buildPerHorizonSpaghettiEntries(forecastRoot: {
     forecasts?: Record<string, Record<string, number>>;
 } | null | undefined, horizonKeys: string[]): RealBacktestsEntry[];
 /**
  * Same row alignment as {@link buildPerHorizonSpaghettiEntries}: row `i` uses each horizon's
- * i-th sorted forecast month; `dates[i]` is horizon_1's month at that row (Date column).
+ * latest-aligned forecast month; `dates[i]` is horizon_1's month at that row (Date column).
  * Use this for custom dialog seed + “copy statistical baseline (drift)” prefill.
  */
 export declare function buildDriftSpaghettiMatrixForCustomDialog(driftRoot: {
@@ -38,6 +38,26 @@ export declare function buildDriftSpaghettiMatrixForCustomDialog(driftRoot: {
     grid: number[][];
     perHorizonDates: string[][];
 } | null;
+export declare function latestHistoricalMonthKey(historicalByDate: Map<string, number>): string | null;
+/**
+ * Append monthly spaghetti rows after drift backtests so the dialog (and chart) reach the latest
+ * historical month (e.g. Apr 2026), not only the last drift origin (e.g. Nov 2025).
+ */
+export declare function extendCustomPerformanceDriftSeedToHistoricalEnd(seed: {
+    dates: string[];
+    grid: number[][];
+    perHorizonDates: string[][];
+}, historicalByDate: Map<string, number>): {
+    dates: string[];
+    grid: number[][];
+    perHorizonDates: string[][];
+};
+/** Pad a saved custom matrix with drift/baseline rows so edit + chart cover latest backtest months. */
+export declare function extendCustomPerformanceMatrixWithDriftSeed(saved: SpaghettiPerformanceMatrixPayload, driftSeed: {
+    dates: string[];
+    grid: number[][];
+    perHorizonDates: string[][];
+}, baselineGrid?: number[][]): SpaghettiPerformanceMatrixPayload;
 /**
  * Prefill for custom performance when copying drift layout: each spaghetti row is flat at the
  * historical value for the month before the earliest forecast month in that row (same anchor as

package/dist/esm/types/src/docs/pages/IncludeHiddenInYScalePage.d.ts

@@ -0,0 +1 @@
+export default function IncludeHiddenInYScalePage(): import("react/jsx-runtime").JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sybilion/uilib",
-  "version": "1.3.63",
+  "version": "1.3.65",
   "description": "Sybilion Design System — React UI components (Webpack + Stylus)",
   "publishConfig": {
     "access": "public",
@@ -42,6 +42,7 @@
     "docs",
     "src",
     "dist",
+    "dist/agent-glossary",
     "package.json"
   ],
   "directories": {
@@ -53,7 +54,8 @@
     "ts": "tsc --noEmit",
     "dev": "NODE_OPTIONS='--loader ts-node/esm' NODE_ENV=development webpack-dev-server --mode=development --config ./src/docs/config/webpack.config.js --progress",
     "prebuild": "cp src/components/ui/Logo/logo.svg assets/logo.svg",
-    "build": "rollup -c rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "build:agent-glossary": "node scripts/build-agent-glossary.mjs --all",
+    "build": "yarn build:agent-glossary && rollup -c rollup.config.ts --configPlugin @rollup/plugin-typescript",
     "build:watch": "yarn build --watch",
     "build:compress": "COMPRESS=true yarn build",
     "publish:npm": "yarn build && npm publish --access public",

package/src/components/ui/Chart/components/BaseChartWrapper.tsx

@@ -121,6 +121,8 @@ export interface BaseChartWrapperProps {
   showActiveDots?: boolean;
   overlayElements?: ReactNode;
   hiddenSeries?: Set<string>;
+  /** When false (default), hidden series values are excluded from Y-axis domain calculation. */
+  includeHiddenInYScale?: boolean;
   excludeLegendIds?: number[];
   onAnalysisSelect?: (analysisId: number | string) => void;
   onFailedAnalysisClick?: (analysisId?: number | string) => void;
@@ -225,6 +227,7 @@ const BaseChartWrapperContent = forwardRef<
     showActiveDots = true,
     overlayElements,
     hiddenSeries,
+    includeHiddenInYScale = false,
     excludeLegendIds,
     onAnalysisSelect,
     onFailedAnalysisClick,
@@ -567,12 +570,19 @@ const BaseChartWrapperContent = forwardRef<
   let effectiveAutoScale = autoScaleYAxis;
   if (autoScaleYAxis !== false && yMin !== undefined && yMax !== undefined) {
     const dataKeys = chartData.length > 0 ? Object.keys(chartData[0]) : [];
-    const historicalValues = chartData
-      .map(p => p.historical)
-      .filter(v => v !== null && v !== undefined);
+    const historicalValues =
+      !includeHiddenInYScale && hiddenSeries?.has('historical')
+        ? []
+        : chartData
+            .map(p => p.historical)
+            .filter(v => v !== null && v !== undefined);
     const forecastKeys = dataKeys.filter(k => k.startsWith('forecast_'));
+    const visibleForecastKeys =
+      !includeHiddenInYScale && hiddenSeries
+        ? forecastKeys.filter(k => !hiddenSeries.has(k))
+        : forecastKeys;
     const forecastValues = chartData
-      .flatMap(p => forecastKeys.map(k => p[k]))
+      .flatMap(p => visibleForecastKeys.map(k => p[k]))
       .filter(v => v !== null && v !== undefined);
     const allLineValues = [...historicalValues, ...forecastValues];
 

package/src/components/ui/ChartAreaInteractive/ChartAreaInteractive.helpers.ts

@@ -67,9 +67,6 @@ const timeRangeToMonths = {
 
 export type TimeRangePreset = keyof typeof timeRangeToMonths;
 
-/** @deprecated Use `TimeRangePreset` or `string` for brush-encoded ranges. */
-export type TimeRange = TimeRangePreset;
-
 export const DRAG_TIME_RANGE_PREFIX = '__drag:' as const;
 
 export function encodeDragTimeRange(a: Date, b: Date): string {
@@ -258,3 +255,7 @@ export const isAnalysisFailed = (
 export const isAnalysisNotFailed = (
   analysis: Analysis | { status?: string },
 ): boolean => !isAnalysisFailed(analysis);
+
+export const isAnalysisDone = (
+  analysis: Analysis | { status?: string },
+): boolean => analysis.status?.toLowerCase() === 'done';

package/src/components/ui/ChartAreaInteractive/index.ts

@@ -1,3 +1,5 @@
 export * from './ChartAreaInteractive';
+export * from './ChartAreaInteractive.helpers';
 export * from './ChartAreaInteractive.types';
+export * from './ChartLines';
 export type { OverlayMode } from './ChartAreaInteractive.types';

package/src/components/ui/ChartAreaInteractive/overlays/useChartYRange.test.ts

@@ -0,0 +1,87 @@
+import { ChartDataPoint } from '#uilib/components/ui/ChartAreaInteractive/ChartAreaInteractive.types';
+
+import {
+  calculateChartYRange,
+  isKeyExcludedFromYScale,
+} from './useChartYRange';
+
+const makePoint = (values: Record<string, number>): ChartDataPoint => ({
+  date: '2024-01-01',
+  ...values,
+});
+
+describe('isKeyExcludedFromYScale', () => {
+  it('excludes historical when hidden', () => {
+    expect(isKeyExcludedFromYScale('historical', new Set(['historical']))).toBe(
+      true,
+    );
+  });
+
+  it('excludes quantile keys when parent forecast is hidden', () => {
+    expect(
+      isKeyExcludedFromYScale('q0.05_123', new Set(['forecast_123'])),
+    ).toBe(true);
+  });
+
+  it('excludes band keys when parent forecast is hidden', () => {
+    expect(
+      isKeyExcludedFromYScale('band_10_90_123', new Set(['forecast_123'])),
+    ).toBe(true);
+  });
+});
+
+describe('calculateChartYRange hidden series exclusion', () => {
+  const chartData: ChartDataPoint[] = [
+    makePoint({ historical: 10, forecast_1: 100, forecast_2: 50 }),
+  ];
+
+  it('pin mode: two forecasts, one hidden - Y range from visible only', () => {
+    const hiddenSeries = new Set(['forecast_1']);
+    const range = calculateChartYRange(chartData, {
+      excludeQuantileBands: true,
+      hiddenSeries,
+      includeHiddenInYScale: false,
+    });
+
+    expect(range).toEqual({ yMin: 6, yMax: 54 });
+  });
+
+  it('hidden historical excluded from Y range', () => {
+    const dataWithOutlierHistorical: ChartDataPoint[] = [
+      makePoint({ historical: 1000, forecast_1: 50, forecast_2: 60 }),
+    ];
+    const hiddenSeries = new Set(['historical']);
+    const range = calculateChartYRange(dataWithOutlierHistorical, {
+      excludeQuantileBands: true,
+      hiddenSeries,
+      includeHiddenInYScale: false,
+    });
+
+    expect(range).toEqual({ yMin: 49, yMax: 61 });
+  });
+
+  it('includeHiddenInYScale=true preserves old behavior', () => {
+    const hiddenSeries = new Set(['forecast_1']);
+    const range = calculateChartYRange(chartData, {
+      excludeQuantileBands: true,
+      hiddenSeries,
+      includeHiddenInYScale: true,
+    });
+
+    expect(range).toEqual({ yMin: 1, yMax: 109 });
+  });
+
+  it('quantile keys excluded when forecast hidden', () => {
+    const dataWithQuantile: ChartDataPoint[] = [
+      makePoint({ forecast_456: 50, forecast_789: 70, 'q0.05_123': 500 }),
+    ];
+    const hiddenSeries = new Set(['forecast_123']);
+    const range = calculateChartYRange(dataWithQuantile, {
+      excludeQuantileBands: false,
+      hiddenSeries,
+      includeHiddenInYScale: false,
+    });
+
+    expect(range).toEqual({ yMin: 48, yMax: 72 });
+  });
+});

package/src/components/ui/ChartAreaInteractive/overlays/useChartYRange.ts

@@ -11,6 +11,137 @@ interface UseChartYRangeOptions {
   selectedForecastId?: number;
 }
 
+export interface CalculateChartYRangeOptions {
+  excludeQuantileBands: boolean;
+  forecastId?: number;
+  hiddenSeries?: Set<string>;
+  includeHiddenInYScale?: boolean;
+}
+
+/** Serialize hidden series keys for stable cache comparison. */
+function serializeHiddenSeries(hiddenSeries?: Set<string>): string {
+  if (!hiddenSeries || hiddenSeries.size === 0) return '';
+  return [...hiddenSeries].sort().join(',');
+}
+
+/**
+ * Returns true when a chart data key should be skipped for Y-scale (series hidden).
+ */
+export function isKeyExcludedFromYScale(
+  key: string,
+  hiddenSeries?: Set<string>,
+): boolean {
+  if (!hiddenSeries || hiddenSeries.size === 0) return false;
+
+  if (key === 'historical') {
+    return hiddenSeries.has('historical');
+  }
+
+  if (key.startsWith('forecast_')) {
+    return hiddenSeries.has(key);
+  }
+
+  if (key.startsWith('q') && key.includes('_')) {
+    const forecastId = key.slice(key.lastIndexOf('_') + 1);
+    return hiddenSeries.has(`forecast_${forecastId}`);
+  }
+
+  if (key.startsWith('band_')) {
+    const forecastId = key.slice(key.lastIndexOf('_') + 1);
+    return hiddenSeries.has(`forecast_${forecastId}`);
+  }
+
+  return false;
+}
+
+/** Pure Y-range calculation from chart data points. */
+export function calculateChartYRange(
+  dataToUse: ChartDataPoint[],
+  {
+    excludeQuantileBands,
+    forecastId,
+    hiddenSeries,
+    includeHiddenInYScale = false,
+  }: CalculateChartYRangeOptions,
+) {
+  const allValues: number[] = [];
+
+  dataToUse.forEach(point => {
+    Object.entries(point).forEach(([key, value]) => {
+      if (key === 'date') return;
+
+      if (
+        !includeHiddenInYScale &&
+        isKeyExcludedFromYScale(key, hiddenSeries)
+      ) {
+        return;
+      }
+
+      // When selectedForecastId is provided, scale from historical + selected forecast + its
+      // quantile band (exclude other forecasts and their quantile values only).
+      if (forecastId !== undefined) {
+        if (key.startsWith('forecast_') && key !== `forecast_${forecastId}`)
+          return;
+        // Exclude q{quantile}_{otherAnalysisId} - only include selected forecast's quantiles
+        if (key.startsWith('q') && !key.endsWith(`_${forecastId}`)) return;
+      }
+
+      // When excludeQuantileBands is true, exclude:
+      // 1. Quantile band arrays ([number, number])
+      // 2. Individual quantile values (q{quantile}_{analysisId} properties)
+      // Only include historical and forecast line values
+      if (excludeQuantileBands) {
+        // Skip quantile band arrays
+        if (
+          Array.isArray(value) &&
+          value.length === 2 &&
+          typeof value[0] === 'number' &&
+          typeof value[1] === 'number'
+        ) {
+          return;
+        }
+
+        // Skip individual quantile values (properties starting with 'q' followed by number/underscore)
+        // Format: q{quantile}_{analysisId} (e.g., q0.05_123, q0.95_123)
+        if (key.startsWith('q') && typeof value === 'number') {
+          return;
+        }
+
+        // Include only historical and forecast line values
+        if (typeof value === 'number') {
+          allValues.push(value);
+        }
+        return;
+      }
+
+      // When not excluding, include both numbers and quantile band arrays
+      if (typeof value === 'number') {
+        allValues.push(value);
+      } else if (
+        Array.isArray(value) &&
+        value.length === 2 &&
+        typeof value[0] === 'number' &&
+        typeof value[1] === 'number'
+      ) {
+        allValues.push(value[0], value[1]);
+      }
+    });
+  });
+
+  if (allValues.length === 0) {
+    return { yMin: 0, yMax: 100 };
+  }
+
+  const min = Math.min(...allValues);
+  const max = Math.max(...allValues);
+  const diff = max - min;
+
+  return {
+    yMin: min - diff * 0.1,
+    yMax: max + diff * 0.1,
+  };
+}
+
 /**
  * Hook to calculate yMin and yMax from chart data
  * Optionally includes quantile values from forecast data
@@ -22,6 +153,9 @@ export function useChartYRange({
   excludeQuantileBands = false,
   selectedForecastId,
 }: UseChartYRangeOptions) {
+  const includeHiddenInYScale = baseChartProps.includeHiddenInYScale ?? false;
+  const hiddenSeries = baseChartProps.hiddenSeries;
+
   // Store initial Y-range when disableRescaleWhenQuantileChanges is true
   const stableYRangeRef = useRef<{
     yMin: number;
@@ -29,84 +163,20 @@ export function useChartYRange({
     forecastId?: number;
   } | null>(null);
   const prevBaseChartDataRef = useRef(baseChartProps.chartData);
+  const prevHiddenSeriesKeyRef = useRef(serializeHiddenSeries(hiddenSeries));
 
-  // Helper function to calculate Y-range from data
   const calculateYRange = (
     dataToUse: ChartDataPoint[],
-    excludeQuantileBands: boolean,
+    excludeBands: boolean,
     forecastId?: number,
-  ) => {
-    const allValues: number[] = [];
-
-    dataToUse.forEach(point => {
-      Object.entries(point).forEach(([key, value]) => {
-        if (key === 'date') return;
-
-        // When selectedForecastId is provided, scale from historical + selected forecast + its
-        // quantile band (exclude other forecasts and their quantile values only).
-        if (forecastId !== undefined) {
-          if (key.startsWith('forecast_') && key !== `forecast_${forecastId}`)
-            return;
-          // Exclude q{quantile}_{otherAnalysisId} - only include selected forecast's quantiles
-          if (key.startsWith('q') && !key.endsWith(`_${forecastId}`)) return;
-        }
-
-        // When excludeQuantileBands is true, exclude:
-        // 1. Quantile band arrays ([number, number])
-        // 2. Individual quantile values (q{quantile}_{analysisId} properties)
-        // Only include historical and forecast line values
-        if (excludeQuantileBands) {
-          // Skip quantile band arrays
-          if (
-            Array.isArray(value) &&
-            value.length === 2 &&
-            typeof value[0] === 'number' &&
-            typeof value[1] === 'number'
-          ) {
-            return;
-          }
-
-          // Skip individual quantile values (properties starting with 'q' followed by number/underscore)
-          // Format: q{quantile}_{analysisId} (e.g., q0.05_123, q0.95_123)
-          if (key.startsWith('q') && typeof value === 'number') {
-            return;
-          }
-
-          // Include only historical and forecast line values
-          if (typeof value === 'number') {
-            allValues.push(value);
-          }
-          return;
-        }
-
-        // When not excluding, include both numbers and quantile band arrays
-        if (typeof value === 'number') {
-          allValues.push(value);
-        } else if (
-          Array.isArray(value) &&
-          value.length === 2 &&
-          typeof value[0] === 'number' &&
-          typeof value[1] === 'number'
-        ) {
-          allValues.push(value[0], value[1]);
-        }
-      });
+  ) =>
+    calculateChartYRange(dataToUse, {
+      excludeQuantileBands: excludeBands,
+      forecastId,
+      hiddenSeries,
+      includeHiddenInYScale,
     });
 
-    if (allValues.length === 0) {
-      return { yMin: 0, yMax: 100 };
-    }
-
-    const min = Math.min(...allValues);
-    const max = Math.max(...allValues);
-    const diff = max - min;
-
-    return {
-      yMin: min - diff * 0.1,
-      yMax: max + diff * 0.1,
-    };
-  };
-
   // When disableRescaleWhenQuantileChanges is true, calculate initial stable range
   // If chartData (transformedChartData) is provided, use it WITH quantile bands for initial calculation
   // Then keep it stable when dragging quantiles
@@ -125,7 +195,7 @@ export function useChartYRange({
       return null;
     }
 
-    // Reset stable range when dataset or selected forecast changes
+    // Reset stable range when dataset, selected forecast, or hidden series changes
     if (prevBaseChartDataRef.current !== baseChartProps.chartData) {
       prevBaseChartDataRef.current = baseChartProps.chartData;
       stableYRangeRef.current = null;
@@ -133,6 +203,11 @@ export function useChartYRange({
     if (stableYRangeRef.current?.forecastId !== selectedForecastId) {
       stableYRangeRef.current = null;
     }
+    const hiddenSeriesKey = serializeHiddenSeries(hiddenSeries);
+    if (prevHiddenSeriesKeyRef.current !== hiddenSeriesKey) {
+      prevHiddenSeriesKeyRef.current = hiddenSeriesKey;
+      stableYRangeRef.current = null;
+    }
 
     // If chartData (transformedChartData) is provided, use it WITH quantile bands for initial calculation
     // This ensures IntervalsOverlay includes quantile bands in Y-scale
@@ -164,6 +239,8 @@ export function useChartYRange({
     disableRescaleWhenQuantileChanges,
     excludeQuantileBands,
     selectedForecastId,
+    hiddenSeries,
+    includeHiddenInYScale,
   ]);
 
   // When disableRescaleWhenQuantileChanges is false, calculate from transformed data
@@ -192,6 +269,8 @@ export function useChartYRange({
     disableRescaleWhenQuantileChanges,
     excludeQuantileBands,
     selectedForecastId,
+    hiddenSeries,
+    includeHiddenInYScale,
   ]);
 
   // Return appropriate range

package/src/components/ui/Page/AGENT.md

@@ -0,0 +1,165 @@
+# Page layout system
+
+Sybilion workspace and report surfaces use a small set of **Page** primitives from `@sybilion/uilib`. Agents must compose these instead of inventing layout with inline styles, Tailwind structure classes, or ad-hoc wrappers.
+
+## Two modes
+
+| Mode               | When                                             | Shell                                                                                 |
+| ------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| **workspace-page** | Route inside `AppShell` / scrolled main column   | `PageHeader` → `PageContent` → `PageContentSection`(s). Optional `PageTabs`.          |
+| **content**        | Report tiles, json-dashboard, embedded body only | No `PageHeader` / `AppShell` chrome. Map React blocks to dashboard tiles (see below). |
+
+Do not nest workspace shell components inside **content** mode output.
+
+## Mandatory workspace-page skeleton
+
+```tsx
+<PageHeader title="…" subheader="…" breadcrumbs={[…]} actions={…} />
+<PageContent>
+  <PageContentSection>{/* section A */}</PageContentSection>
+  <PageContentSection grow={false}>{/* section B */}</PageContentSection>
+</PageContent>
+```
+
+- **PageHeader**: one per route view in the main column; title, optional subheader, breadcrumbs, actions.
+- **PageContent**: vertical stack for the body below the header; `variant="clean"` when you need a flatter body (no extra chrome).
+- **PageContentSection**: primary vertical band; applies horizontal **page-x-padding** via Stylus (`pageXPadding()`). Use multiple sections to separate logical blocks.
+
+Global tokens (host app `:root`, e.g. `standalone-global.css`): `--page-width`, `--page-x-padding`, `--page-y-padding`. `PageContent` caps width at `--page-width`.
+
+## PageTabs — rules and patterns
+
+**NEVER** place `PageTabs` inside `PageContentSection`. Tabs manage their own horizontal inset via `PageXScroll` / `tabsListProps.withPaddings`.
+
+### Unified (tabs + panels inside PageContent)
+
+```tsx
+<PageHeader … />
+<PageContent>
+  <PageTabs
+    items={[
+      { value: 'a', label: 'Tab A', content: <PageContentSection>…</PageContentSection> },
+      { value: 'b', label: 'Tab B', content: <PageContentSection>…</PageContentSection> },
+    ]}
+  />
+</PageContent>
+```
+
+Tab **panels** use `PageContentSection` so section padding stays correct.
+
+### Split (bar-only sibling)
+
+Use when the tab bar must sit between header and a custom scroll region:
+
+```tsx
+<PageHeader … />
+<PageTabs
+  items={[
+    { value: 'a', label: 'Tab A', content: null },
+    { value: 'b', label: 'Tab B', content: null },
+  ]}
+/>
+<PageContent>…</PageContent>
+```
+
+Set `content: null` (or omit) for bar-only items; render panel bodies in `PageContent` yourself.
+
+## Spacing ownership
+
+| Component              | Owns horizontal page padding?                             |
+| ---------------------- | --------------------------------------------------------- |
+| **PageContentSection** | Yes (`pageXPadding`)                                      |
+| **PageTabs**           | Via `tabsListProps.withPaddings` + internal `PageXScroll` |
+| **PageXScroll**        | Reads `--page-x-padding` for inset when used standalone   |
+| **PageHeader**         | Own header inner layout (not `PageContentSection`)        |
+
+Do not duplicate `padding-left/right` on children that already sit in `PageContentSection`.
+
+## Styling rules
+
+- **No** `style={{…}}` for layout or spacing (margins, padding, flex, width, gap).
+- **No** Tailwind (or other) utility classes for **structural** layout on page primitives.
+- Custom layout CSS only in co-located `ComponentName.styl`, using design tokens (`var(--p-*)`, `var(--page-x-padding)`, `pageXPadding()`, etc.).
+- `className` on Page components is for Stylus module classes or state hooks, not one-off pixel tweaks.
+
+## Component reference
+
+### PageHeader
+
+Sticky-style page title row: breadcrumbs (optional sidebar trigger in full app), `title`, `subheader`, `actions`. Lives **above** `PageContent`, never inside a section.
+
+### PageContent / PageContentSection
+
+`PageContent`: column flex child, `max-width: var(--page-width)`.  
+`PageContentSection`: `grow` (default `true`) lets the section absorb remaining height in flex layouts.
+
+### PageColumns
+
+Side-by-side columns with gap. **`fill`** controls which column(s) grow:
+
+| `fill`          | Behavior                                                                                        |
+| --------------- | ----------------------------------------------------------------------------------------------- |
+| `all` (default) | Every column `flex-grow: 1`, `max-width` unset — use for equal split or fluid grids of columns. |
+| `left`          | First column grows; others stay at fixed min/max column width.                                  |
+| `right`         | Last column grows.                                                                              |
+
+Pass `columns={[node1, node2, …]}`. On mobile, stacks vertically. Typical pattern: main + aside inside one `PageContentSection`.
+
+### PageXScroll
+
+Horizontal scroll strip; used inside `PageTabs` and anywhere a overflowing row needs page-aligned padding. Props: `size`, `fullWidth`, `innerClassName`, `scrollbarClassName`.
+
+### SectionHeader
+
+In-section title block (`title`, `description`, `actions`). Use **inside** `PageContentSection`, not as a replacement for `PageHeader`.
+
+### PageEmptyCanvas
+
+Centered empty state: `title`, `hint`, optional `children` (e.g. CTA button). Use when a route has no data yet.
+
+### GridLayout
+
+Responsive CSS grid (`repeat(auto-fit, minmax(colWidth, 1fr))`). Use for card/tile dashboards inside a section. Report mapping: dashboard **grid** rows / multi-column tile groups.
+
+### Card / Foldable
+
+Use inside sections for grouped content; see package `AGENT.md` on those components when present. Do not wrap the whole page in Card.
+
+## Content mode — React → json-dashboard tiles
+
+When generating **report** / dashboard specs (not workspace routes), map UI blocks to tiles:
+
+| React / intent                  | Dashboard tile / markdown                                         |
+| ------------------------------- | ----------------------------------------------------------------- |
+| `PageHeader` title text         | First `markdown` tile `# Title` or report title field             |
+| `SectionHeader` `title`         | `markdown` with `## …`                                            |
+| `SectionHeader` `description`   | markdown paragraph under that heading                             |
+| `PageContentSection` block      | group of tiles or one markdown section                            |
+| `GridLayout` children           | grid row of widget tiles                                          |
+| `ChartAreaInteractive` / charts | `dataset_card`, `performance_chart`, etc. (see widget `AGENT.md`) |
+| `PageEmptyCanvas` copy          | `markdown` explanatory tile                                       |
+
+See `AGENT.report-only-tiles.md` in the app repo for tiles without a uilib widget.
+
+## Shell components (workspace only)
+
+Not part of the per-route skeleton but part of **workspace-page** host wiring:
+
+- **AppShell** / **AppShellMainContent** — sidebar + main column + header slot + footer.
+- **PageScroll** — scroll root for the main column.
+- **SybilionAppHeader** — workspace app switcher + user menu (lives in header slot, not inside `PageContent`).
+
+## Anti-patterns
+
+- `PageTabs` inside `PageContentSection`.
+- Inline styles or Tailwind for page structure.
+- Second `PageHeader` nested in content.
+- `PageContent` without sections for multi-block pages (prefer multiple `PageContentSection`).
+- Wrapping data widgets in extra layout divs with hard-coded padding.
+
+## Future candidates (not implemented)
+
+- **PageToolbar** — dedicated action row between header and tabs.
+- **PageFullBleed** — edge-to-edge section escape hatch.
+
+Do not add these locally; extend uilib when product needs them.

package/src/components/widgets/AGENT.md

@@ -6,7 +6,7 @@ Each component file ≤18 lines. Signal for LLM prompts — no noise.
 
 **Include:** Renders (1 sentence); Use when / Not when; Host provides (3–5 bullets); Report tile (one line or "Not used"); Requires (prop names + role); Empty/loading (one line).
 
-**Do not include:** import examples; type/doc/demo/glossary links; page-shell boilerplate; related-components lists unless choosing between exports; implementation/styling/keyboard notes unless binding-relevant; secrets, env vars, API URLs.
+**Do not include:** import examples; type/doc/demo/glossary links; page-shell boilerplate; related-components lists unless choosing between exports; implementation/styling/keyboard notes unless binding-relevant; secrets, env vars, API URLs; inline style examples (`style={{…}}`).
 
 ```markdown
 # Name