@graphenedata/cli 0.0.16 → 0.0.18

package/dist/skills/graphene/references/model-gsql.md

@@ -1,29 +1,27 @@
 # Modeling GSQL
 
-Conventions and patterns for writing production-quality `.gsql` semantic models. For GSQL syntax reference, see `references/gsql.md`.
+Conventions and patterns for writing production-quality `.gsql` semantic models. Make sure you've read `references/gsql.md` before proceeding.
 
-## Quick start: New table workflow
+## New table workflow
 
-1. Generate a `.gsql` file from the base schema: `npx graphene schema {DB.SCHEMA.TABLE} > tables/{snake_case_table_name}.gsql`
+1. Generate a plain `.gsql` file first: `graphene schema {DB.SCHEMA.TABLE} > tables/{snake_case_table_name}.gsql`
 2. Add table and grain descriptions at the top of the file. If given a dbt project, look up the table's definition, lineage, and related metadata so that you have the full picture.
 3. Add join relationships.
+   - If no join documentation is provided, make an educated guess from PK/FK names.
+   - Use `graphene run <query>` to confirm the join works as expected: keys match, row counts are sane, and there is no fan-out.
+   - Model joins from boths sides (ie. add the join to each respective `table` statement)
 
-- If no join documentation is provided, make an educated guess from PK/FK names.
-- Use `npx graphene run <query>` to confirm the join works as expected: keys match, row counts are sane, and there is no fan-out.
+4. Add dimensions and measures **ONLY** if a semantic model to migrate from has been provided.
+   - Compile-verify: `npx graphene compile "from TABLE select dimension1, dimension2, measure1, measure2"`
 
-4. Add dimensions and measures only if a semantic model to migrate from has been provided.
+5. Add descriptions to columns, dimensions, and measures via comments.
+   - Do not add a description if it already obvious from the name. For example, skip `is_debooked_opportunity BOOLEAN -- Whether the opportunity has been debooked`.
+   - Use example values for categorical columns: `graphene run "from TABLE select distinct col limit 10"`.
+   - Add synonyms, but only if provided. **DO NOT** guess them.
+   - Descriptions can be inlined or placed as a block comment on the line above.
 
-- Do not invent dimensions or measures. Only codify known query patterns.
-- Compile-verify: `npx graphene compile "from TABLE select dimension1, dimension2, measure1, measure2"`
-
-5. Add descriptions via comments.
-
-- Only add a comment when the column name is not self-explanatory. For example, skip `is_debooked_opportunity BOOLEAN -- Whether the opportunity has been debooked`.
-- Use example values for categorical columns: `npx graphene run "from TABLE select distinct col limit 10"`.
-- Add synonyms only if provided. Do not guess them.
-- Descriptions can be inlined or placed as a block comment on the line above.
-
-6. Add GSQL metadata annotations where applicable eg. `#ratio`, `#pct`, `#timeGrain=day`, etc. 
+6. Add GSQL metadata annotations where applicable eg. `#ratio`, `#pct`, `#timeGrain=day`, etc.
+   - Use only annotations that Graphene recognizes (see `references/gsql.md`)
 
 ## File structure
 
@@ -36,7 +34,7 @@ table DATABASE.SCHEMA.TABLE_NAME (
 
   /* Sub-section headers as needed, to group up fields if there are many columns */
 
-  column_name TYPE -- Description/metadata if necessary
+  column_name TYPE -- A description and a #annotation
 
   -- OR, descriptions/metadata for a field/dimension/measure can be on the lines above it
   -- as long as there is NOT an empty line separating
@@ -48,11 +46,11 @@ table DATABASE.SCHEMA.TABLE_NAME (
 
   /* Dimensions */
 
-  dim_name: expression -- Description/metadata if necessary
+  dim_name: expression #annotationWithoutDescription
 
   /* Measures */
 
-  measure_name: aggregate_expression -- Description/metadata if necessary
+  measure_name: aggregate_expression
 )
 
 /* Example queries */ -- Only if correct query usage patterns are not obvious
@@ -68,5 +66,5 @@ Section headers use `/* Header */` style. Section headers need a full newline fo
 
 Always verify after changes. A parse error in any `.gsql` file prevents all tables from loading. If you see "Unknown table" errors everywhere, check for syntax errors in recently modified files.
 
-You can syntax check the whole project with `npx graphene check`.
+You can syntax check the whole project with `graphene check`.
 

package/dist/ui/component-utilities/enrich.ts

@@ -284,6 +284,20 @@ function inferAxesFromEncodedFields(config: NormalConfig, fields: Field[], rows:
 
     config.yAxis[axisIndex] = {...inferred, ...axis, axisLabel: {...inferred.axisLabel, ...axis.axisLabel}, axisPointer: {...inferred.axisPointer, ...axis.axisPointer}}
   }
+
+  // Ordinal x axes already use labels to communicate the bucket boundaries, so
+  // the y-axis line reads like an extra vertical grid line at the left edge.
+  // Hide the paired y-axis line unless the caller explicitly configured it.
+  for (let [axisIndex, axis] of config.xAxis.entries()) {
+    if (!axis?.field?.metadata?.timeOrdinal && axis?.field?.metadata?.timeGrain !== 'year') continue
+
+    let yAxisIndexes = config.series.filter(entry => Number(entry?.xAxisIndex ?? 0) === axisIndex).map(entry => Number(entry?.yAxisIndex ?? 0))
+    for (let yAxisIndex of yAxisIndexes) {
+      let yAxis = config.yAxis[yAxisIndex]
+      if (!yAxis || yAxis.axisLine?.show != null) continue
+      yAxis.axisLine = {...yAxis.axisLine, show: false}
+    }
+  }
 }
 
 // Value-axis bars are centered on their x/y value, so explicit min/max domains clip edge bars.
@@ -392,7 +406,7 @@ function valueFormatting(config: NormalConfig, fields: Field[]) {
   let valueAxes = [...config.xAxis, ...config.yAxis].filter(axis => axis?.type === 'value' && !axis.field?.metadata?.timeOrdinal)
   for (let axis of valueAxes) {
     if (axis.axisLabel?.formatter != null) continue
-    axis.axisLabel = {...axis.axisLabel, formatter: makeValueFormatter(axis.field ? [axis.field] : [])}
+    axis.axisLabel = {...axis.axisLabel, formatter: makeValueFormatter(axis.field ? [axis.field] : [], {unitStyle: 'axis'})}
   }
 
   for (let series of config.series) {
@@ -494,22 +508,24 @@ function barLabelPositioning(config: NormalConfig) {
   }
 }
 
-// Match series data labels to the assigned y-axis formatter when labels are enabled.
-// This keeps label formatting in sync with the y-axis without asking callers to repeat it.
-// labelsUseYAxisFormat depends on valueAxisFormatting running first so labels inherit axis formatting.
+// Match series data labels to the assigned value field when labels are enabled.
+// This keeps label formatting in sync with tooltips without asking callers to repeat it.
+// labelsUseYAxisFormat depends on valueFormatting running first so labels inherit axis formatting.
 function labelsUseYAxisFormat(config: NormalConfig, fields: Field[]) {
   for (let series of config.series) {
     // No-op when labels are off or already explicitly formatted.
     if (!series?.label || series.label.show !== true || series.label.formatter != null) continue
 
-    let yField = getSeriesValueField(series, fields)?.name
+    let valueField = getSeriesValueField(series, fields)
+    let yField = valueField?.name
     let axisIndex = Number(series.yAxisIndex ?? 0)
     let axisFormatter = config.yAxis[axisIndex]?.axisLabel?.formatter
-    if (typeof axisFormatter !== 'function') continue
+    let labelFormatter = valueField ? makeValueFormatter([valueField]) : axisFormatter
+    if (typeof labelFormatter !== 'function') continue
 
     // ECharts can pass different value shapes depending on series/transform shape.
     // We resolve the numeric value in a few fallback steps so labels always use the
-    // same value the y-axis is formatting.
+    // same field that tooltips format.
     series.label.formatter = (params: unknown) => {
       let typed = params as {value?: unknown; data?: Record<string, unknown>}
       let value = typed?.value
@@ -521,7 +537,7 @@ function labelsUseYAxisFormat(config: NormalConfig, fields: Field[]) {
         }
       }
 
-      return formatAxisValue(axisFormatter, value)
+      return formatAxisValue(labelFormatter, value)
     }
   }
 }
@@ -664,20 +680,34 @@ function inferAxisFromField(field: Field | undefined, rows: Record<string, any>[
       axis.max = domain[1]
     }
 
+    if (field.metadata?.timeGrain === 'year') {
+      // Pin year ticks to evenly-spaced integers so a domain like [2000, 2005]
+      // doesn't end up with the 2000/2002/2004/2005 stub-label pattern.
+      let ticks = domain ? niceIntegerTicks(domain[0], domain[1]) : []
+      axis.axisLabel = {customValues: ticks, formatter: (value: unknown) => (Number.isInteger(Number(value)) ? String(Number(value)) : '')}
+      axis.axisTick = {customValues: ticks}
+      axis.axisLine = {show: false}
+      axis.splitLine = {show: false}
+      return axis
+    }
+
     if (field.metadata?.timeOrdinal) {
-      axis.minInterval = 1
-      if (field.metadata.timeOrdinal === 'dow_0s' || field.metadata.timeOrdinal === 'dow_1s' || field.metadata.timeOrdinal === 'dow_1m' || field.metadata.timeOrdinal === 'quarter_of_year') {
-        axis.splitNumber = Math.max(1, domain ? domain[1] - domain[0] + 1 : 5)
+      // Ordinal values are numeric so we use a value axis with a fixed domain, but
+      // visually they are discrete buckets. Hide value-axis grid lines by default
+      // and pin tick positions to evenly-spaced integers so we never get a stub
+      // boundary label (e.g. weeks 1, 14, 27, 40, 53 instead of 1, 11, 21, 31, 41, 51, 53).
+      let ticks = domain ? niceIntegerTicks(domain[0], domain[1]) : []
+      axis.axisLine = {show: false}
+      axis.splitLine = {show: false}
+      axis.axisLabel = {
+        hideOverlap: true,
+        customValues: ticks,
+        formatter: (value: unknown) => (domain && (Number(value) < domain[0] || Number(value) > domain[1]) ? '' : formatTimeOrdinal(field, value)),
       }
-      axis.axisLabel = {formatter: (value: unknown) => (domain && (Number(value) < domain[0] || Number(value) > domain[1]) ? '' : formatTimeOrdinal(field, value))}
+      axis.axisTick = {customValues: ticks}
       axis.axisPointer = {label: {formatter: (value: unknown) => formatTimeOrdinal(field, value)}}
       return axis
     }
-
-    if (field.metadata?.timePart === 'year') {
-      axis.minInterval = 1
-      axis.axisLabel = {formatter: (value: unknown) => (Number.isInteger(Number(value)) ? String(Number(value)) : '')}
-    }
   }
 
   if (type === 'category' && field.metadata?.timeOrdinal) {
@@ -688,9 +718,50 @@ function inferAxisFromField(field: Field | undefined, rows: Record<string, any>[
   return axis
 }
 
+// Pick evenly-spaced integer tick positions across [min, max] for ordinal/year value axes.
+// Strategy:
+//   1. If the range is small enough that labeling every value is readable
+//      (≤ denseLimit, sized to cover the 12-month ordinal), label every value.
+//   2. Otherwise prefer step sizes that divide the range exactly so the last tick
+//      lands on max (avoiding the stub-label problem where ECharts' auto-picked step
+//      doesn't reach max).
+//   3. If no candidate divides the range cleanly, fall back to the smallest step that
+//      fits inside targetMax ticks; the final tick may fall short of max, but the chart's
+//      domain still extends visually via half-bucket padding.
+function niceIntegerTicks(min: number, max: number, targetMin = 4, targetMax = 8, denseLimit = 13): number[] {
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max < min) return []
+  let range = max - min
+  if (range === 0) return [min]
+  if (range + 1 <= denseLimit) return tickRange(min, max, 1)
+
+  let candidates = [1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 5000]
+  for (let step of candidates) {
+    if (range % step !== 0) continue
+    let count = range / step + 1
+    if (count >= targetMin && count <= targetMax) return tickRange(min, max, step)
+  }
+  for (let step of candidates) {
+    let count = Math.floor(range / step) + 1
+    if (count >= targetMin && count <= targetMax) return tickRange(min, max, step)
+  }
+  return [min, max]
+}
+
+function tickRange(min: number, max: number, step: number): number[] {
+  let values: number[] = []
+  for (let v = min; v <= max + 1e-9; v += step) values.push(Math.round(v))
+  return values
+}
+
 // Return the natural numeric domain for temporal values that are encoded as numbers.
 function temporalValueDomain(field: Field, rows: Record<string, any>[]): [number, number] | undefined {
   let ordinal = field.metadata?.timeOrdinal
+  if (field.metadata?.timeGrain === 'year') {
+    let values = rows.map(row => Number(row?.[field.name])).filter(value => Number.isFinite(value))
+    if (values.length === 0) return undefined
+    return [Math.min(...values), Math.max(...values)]
+  }
+
   if (ordinal === 'hour_of_day') return [0, 23]
   if (ordinal === 'day_of_month') return [1, 31]
   if (ordinal === 'day_of_year') return [1, 366]
@@ -699,12 +770,6 @@ function temporalValueDomain(field: Field, rows: Record<string, any>[]): [number
   if (ordinal === 'quarter_of_year') return [1, 4]
   if (ordinal === 'dow_0s') return [0, 6]
   if (ordinal === 'dow_1s' || ordinal === 'dow_1m') return [1, 7]
-
-  if (field.metadata?.timePart == 'year') {
-    let values = rows.map(row => Number(row?.[field.name])).filter(value => Number.isFinite(value))
-    if (values.length === 0) return undefined
-    return [Math.min(...values), Math.max(...values)]
-  }
 }
 
 // Series sometimes encode their value field as `y` and sometimes as `value` (pie, funnel, etc).

package/dist/ui/component-utilities/format.ts

@@ -1,6 +1,6 @@
 import type {Field} from './types.ts'
 
-const currencySymbols = {usd: '$', eur: '€', gbp: '£', cad: 'C$', aud: 'A$', jpy: '¥'} as const
+const supportedCurrencyCodes = new Set(Intl.supportedValuesOf('currency'))
 const percent = new Intl.NumberFormat('en-US', {maximumFractionDigits: 0})
 const currencyCompact = new Intl.NumberFormat('en-US', {notation: 'compact', maximumFractionDigits: 1})
 const monthYearFormatter = new Intl.DateTimeFormat('en-US', {month: 'long', year: 'numeric'})
@@ -11,6 +11,8 @@ const yearMonths = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep
 const titleCaseAcronyms = ['id', 'gdp']
 const titleCaseLowerWords = ['of', 'the', 'and', 'in', 'on']
 
+type ValueFormatterOptions = {unitStyle?: 'label' | 'axis'}
+
 // Formats a raw column name into a readable title.
 export function formatTitle(column: string) {
   let cleaned = column.replace(/"/g, '').replace(/_/g, ' ')
@@ -24,43 +26,56 @@ export function formatTitle(column: string) {
 // ECharts valueFormatter will take different arguments depending on the chart type.
 // For bar/line/area it's just a number
 // for scatter, it's [x,y], for candlestick [open, close, low, high], etc
-export function makeValueFormatter(fields: Field[] = []) {
+export function makeValueFormatter(fields: Field[] = [], options: ValueFormatterOptions = {}) {
   return (value: unknown) => {
-    if (Array.isArray(value)) return value.map((entry, index) => formatSingleValue(entry, fields[index] || fields[0])).join(', ')
-    return formatSingleValue(value, fields[0])
+    if (Array.isArray(value)) return value.map((entry, index) => formatSingleValue(entry, fields[index] || fields[0], options)).join(', ')
+    return formatSingleValue(value, fields[0], options)
   }
 }
 
-// Formats one numeric value with field metadata (units, ratio/pct, compact notation).
-export function formatSingleValue(value: any, field?: Field) {
+// Formats one numeric value with field metadata (currency, ratio/pct, compact notation).
+export function formatSingleValue(value: any, field?: Field, options: ValueFormatterOptions = {}) {
   let amount = Number(value)
   if (!Number.isFinite(amount)) return String(value ?? '')
 
   if (field?.metadata?.ratio) return `${percent.format(amount * 100)}%`
   if (field?.metadata?.pct) return `${percent.format(amount)}%`
 
-  let unit = field?.metadata?.units?.toLowerCase() as keyof typeof currencySymbols | undefined
-  let currencyUnit = unit != null && unit in currencySymbols ? unit : undefined
-  if (currencyUnit) {
+  let currency = field?.metadata?.currency?.toUpperCase()
+  if (currency && supportedCurrencyCodes.has(currency)) {
     let sign = amount < 0 ? '-' : ''
     let formatted = currencyCompact.format(Math.abs(amount)).replace('K', 'k').replace('M', 'm').replace('B', 'b')
-    return `${sign}${currencySymbols[currencyUnit]}${formatted}`
+    return `${sign}${formatCurrencySymbol(currency)}${formatted}`
   }
 
-  if (amount === 0) return '0'
+  if (amount === 0) return addUnit('0', field, options)
   let sign = amount < 0 ? '-' : ''
   let absolute = Math.abs(amount)
+  let formatted = ''
+
+  if (absolute >= 1e12) formatted = `${compactValue(absolute / 1e12)}T`
+  else if (absolute >= 1e9) formatted = `${compactValue(absolute / 1e9)}B`
+  else if (absolute >= 1e6) formatted = `${compactValue(absolute / 1e6)}M`
+  else if (absolute >= 1e3) formatted = `${compactValue(absolute / 1e3)}k`
+  else if (absolute >= 1) formatted = compactValue(absolute)
+  else if (absolute >= 1e-3) formatted = compactValue(absolute)
+  else if (absolute >= 1e-6) formatted = `${compactValue(absolute * 1e3)}m`
+  else if (absolute >= 1e-9) formatted = `${compactValue(absolute * 1e6)}u`
+  else if (absolute >= 1e-12) formatted = `${compactValue(absolute * 1e9)}n`
+  else formatted = compactValue(absolute)
+
+  return addUnit(`${sign}${formatted}`, field, options)
+}
+
+function formatCurrencySymbol(currency: string) {
+  let parts = new Intl.NumberFormat('en-US', {style: 'currency', currency, currencyDisplay: 'symbol', maximumFractionDigits: 0}).formatToParts(0)
+  return parts.find(part => part.type === 'currency')?.value || currency
+}
 
-  if (absolute >= 1e12) return `${sign}${compactValue(absolute / 1e12)}T`
-  if (absolute >= 1e9) return `${sign}${compactValue(absolute / 1e9)}B`
-  if (absolute >= 1e6) return `${sign}${compactValue(absolute / 1e6)}M`
-  if (absolute >= 1e3) return `${sign}${compactValue(absolute / 1e3)}k`
-  if (absolute >= 1) return `${sign}${compactValue(absolute)}`
-  if (absolute >= 1e-3) return `${sign}${compactValue(absolute)}`
-  if (absolute >= 1e-6) return `${sign}${compactValue(absolute * 1e3)}m`
-  if (absolute >= 1e-9) return `${sign}${compactValue(absolute * 1e6)}u`
-  if (absolute >= 1e-12) return `${sign}${compactValue(absolute * 1e9)}n`
-  return `${sign}${compactValue(absolute)}`
+function addUnit(value: string, field: Field | undefined, options: ValueFormatterOptions) {
+  let unit = field?.metadata?.unit?.trim()
+  if (!unit) return value
+  return options.unitStyle === 'axis' ? `${value} (${unit})` : `${value} ${unit}`
 }
 
 // Creates a formatter function that renders date/timestamp values based on field metadata.timeGrain.

package/dist/ui/component-utilities/theme.ts

@@ -111,7 +111,6 @@ registerTheme('graphene-theme', {
     containLabel: false,
   },
   line: {
-    smooth: true,
     symbol: 'emptyCircle',
     symbolSize: 6,
     lineStyle: {width: 2},

package/dist/ui/components/AreaChart.svelte

@@ -59,7 +59,7 @@
       tooltip: {trigger: 'axis'},
       legend: {show: Boolean(splitBy || y2 || yFields.length > 1)},
       xAxis: {},
-      yAxis: [{max: stackPercentage ? 1 : undefined}, ...(y2 ? [{}] : [])],
+      yAxis: [{max: stackPercentage ? 1 : undefined}, ...(y2 ? [{alignTicks: true}] : [])],
       series,
     }
   }

package/dist/ui/components/BarChart.svelte

@@ -75,7 +75,7 @@
       tooltip: {trigger: 'axis'},
       legend: {show: Boolean(splitBy || y2 || (!horizontal && yFields.length > 1) || (horizontal && xFields.length > 1))},
       xAxis: {},
-      yAxis: [{max: stackPercentage ? 1 : undefined}, ...(y2 ? [{}] : [])],
+      yAxis: [{max: stackPercentage ? 1 : undefined}, ...(y2 ? [{alignTicks: true}] : [])],
       series,
     }
   }

package/dist/ui/components/LineChart.svelte

@@ -55,7 +55,7 @@
       tooltip: {trigger: 'axis'},
       legend: {show: Boolean(splitBy || y2 || yFields.length > 1)},
       xAxis: {},
-      yAxis: [{}, ...(y2 ? [{}] : [])],
+      yAxis: [{}, ...(y2 ? [{alignTicks: true}] : [])],
       series,
     }
   }

package/dist/ui/internal/LocalApp.svelte

@@ -19,15 +19,18 @@
   let navData = $state(navFiles)
   import.meta.hot?.accept('virtual:nav', mod => navData = mod.default)
 
+  let pathName = window.location.pathname.replace(/^\//, '') || 'index'
+
   // Track compile errors from both initial load and subsequent HMR failures.
   let compileError = $state<GrapheneError | null>(null)
   import.meta.hot?.on('vite:error', (payload) => {
+    let path = String(payload.err.id || '').split('?')[0].replace(/^file:\/\//, '').replace(/\\/g, '/').replace(/^\/+/, '')
+    if (!path.endsWith(pathName + '.md')) return // ignore errors on md pages that are not this page
+
     let line = Math.max(0, (payload.err.loc?.line || 1) - 1)
     let col = Math.max(0, payload.err.loc?.column || 0)
-    let path = String(payload.err.id || '').replace(/^file:\/\//, '').replace(/\\/g, '/').replace(/^\/+/, '')
-    let message = String(payload.err.message || '').replace(/^.*?:\d+:\d+\s*/, '').replace(/\s*https:\/\/svelte\.dev\/\S+/g, '').trim()
     compileError = {
-      message,
+      message: String(payload.err.message || '').replace(/^.*?:\d+:\d+\s*/, '').replace(/\s*https:\/\/svelte\.dev\/\S+/g, '').trim(),
       frame: payload.err.frame,
       file: path,
       from: {line, col, offset: 0},
@@ -40,33 +43,32 @@
   // The md file is dynamically imported, so even if there's a compile error, we'll still load LocalApp and can show the user the issue
   let Page = $state<any>(null)
   let pageMeta = $state<any>({})
-  let pageReadyResolve: (() => void) | undefined
-  window.$GRAPHENE.pageReady = new Promise<void>(resolve => pageReadyResolve = resolve)
 
   onMount(async () => {
-    let pathName = window.location.pathname.replace(/^\//, '') || 'index'
-
-    // force fonts to load before we mount the component.
-    // This is important for echarts, as it measures text and if done with the wrong font, then
-    // a) when the right font loads, things will just slightly not line up with edges
-    // b) test snapshots will differ, as they measure with whatever the system sans font is
-    // c) screenshots taken by `graphene run` might have the wrong font
-    document.fonts.load("12px 'Source Sans 3'")
-    await document.fonts.ready
+    try {
+      // force fonts to load before we mount the component.
+      // This is important for echarts, as it measures text and if done with the wrong font, then
+      // a) when the right font loads, things will just slightly not line up with edges
+      // b) test snapshots will differ, as they measure with whatever the system sans font is
+      // c) screenshots taken by `graphene run` might have the wrong font
+      document.fonts.load("12px 'Source Sans 3'")
+      await document.fonts.ready
 
-    if (pathName == '_charts') {
-      Page = ChartGallery
-    } else if (pathName == '_styles') {
-      Page = StyleGallery
-    } else if (pathName !== '__ct') {
-      let mod = await import(/* @vite-ignore */ '/' + pathName + '.md')
-      Page = mod.default
-      pageMeta = mod.metadata || {}
-      compileError = null
-      setErrorFor('compile', null)
+      if (pathName == '_charts') {
+        Page = ChartGallery
+      } else if (pathName == '_styles') {
+        Page = StyleGallery
+      } else if (pathName !== '__ct') {
+        let mod = await import(/* @vite-ignore */ '/' + pathName + '.md')
+        Page = mod.default
+        pageMeta = mod.metadata || {}
+        compileError = null
+        setErrorFor('compile', null)
+      }
+    } finally {
+      await tick()
+      window.$GRAPHENE.appLoading = false
     }
-    await tick()
-    pageReadyResolve?.()
   })
 </script>
 
@@ -75,7 +77,7 @@
   <PageNavGroup files={navData} />
 </Sidebar>
 
-<main id="content" class={{pageContent: !!Page, dashboardLayout: pageMeta.layout == 'dashboard'}}>
+<main id="content" class={{pageContent: compileError || !!Page, dashboardLayout: pageMeta.layout == 'dashboard'}}>
   {#if compileError}
     <h1 class="page-error-heading">Error loading page</h1>
     <ErrorDisplay error={compileError} />

package/dist/ui/internal/PageNavGroup.svelte

@@ -115,8 +115,8 @@
     return nodes
       .map(n => n.type === 'folder' && n.children?.length ? {...n, children: sortNodes(n.children)} : n)
       .sort((a, b) => {
-        if (a.label === 'Home') return -1
-        if (b.label === 'Home') return 1
+        if (a.path?.toLowerCase() === 'index.md') return -1
+        if (b.path?.toLowerCase() === 'index.md') return 1
         if (a.type !== b.type) return a.type === 'folder' ? -1 : 1
         return a.label.localeCompare(b.label)
       })

package/dist/ui/internal/Sidebar.svelte

@@ -1,18 +1,18 @@
 <script>
-  // Content-agnostic sidebar shell. The panel slides in as an overlay when the
-  // user hovers the paired SidebarToggle button (rendered separately by the host)
-  // or the panel itself. Styling values are ported from shadcn-svelte's sidebar registry.
+  // Content-agnostic sidebar shell. By default the panel slides in as an overlay
+  // when the user hovers the paired SidebarToggle button or the panel itself;
+  // alwaysOpen keeps the same shell visible for persistent navigation.
   import {sidebar} from './sidebar.svelte.js'
-  let {children, width = '16rem'} = $props()
+  let {children, width = '16rem', alwaysOpen = false} = $props()
 </script>
 
 <nav
   id="nav"
   class="sb-panel pretty-scrollbar"
   style="--sb-w:{width}"
-  data-open={sidebar.open}
-  onmouseenter={sidebar.enter}
-  onmouseleave={sidebar.leave}
+  data-open={alwaysOpen || sidebar.open}
+  onmouseenter={() => { if (!alwaysOpen) sidebar.enter() }}
+  onmouseleave={() => { if (!alwaysOpen) sidebar.leave() }}
 >
   <div class="sb-inner">
     {@render children?.()}

package/dist/ui/internal/queryEngine.ts

@@ -15,7 +15,7 @@ interface QueryNode {
   contents: string
   callback?: ResultHandler
   loading: boolean
-  fields: Map<string, string | string[]>
+  fields: string[]
   componentId?: string
   error?: GrapheneError
 }
@@ -39,24 +39,22 @@ export const setQueryFetcher = f => (queryFetcher = f)
 // Called by GrapheneQuery tags to register a named query on the page
 function registerQuery(name: string, contents: string) {
   queries = queries.filter(q => q.name !== name)
-  queries.push({name, contents, loading: false, fields: new Map()})
+  queries.push({name, contents, loading: false, fields: []})
 }
 
 // Called by viz components to request a particular query of data
 function query(source: string, fields: Record<string, string | string[]>, callback: ResultHandler, componentId?: string) {
-  // using Map here because it preserves the order in which we add fields to the select, which we use when we get the result.
-  let map = new Map(Object.entries(fields))
-  let exprs: string[] = []
-  if (map.size > 0) {
-    map.forEach(value => {
-      if (Array.isArray(value)) exprs.push(...value)
-      else exprs.push(value)
+  // Preserve field order because translateData maps result fields back to requested expressions by index.
+  let seen = new Set<string>()
+  let exprs = Object.values(fields)
+    .flatMap(value => (Array.isArray(value) ? value : [value]))
+    .filter(field => {
+      if (seen.has(field)) return false
+      seen.add(field)
+      return true
     })
-  } else {
-    exprs = ['*']
-  }
-  let contents = `from ${source} select ${exprs.join(', ')}`
-  queries.push({contents, callback, loading: false, fields: map, source, componentId})
+  let contents = `from ${source} select ${(exprs.length ? exprs : ['*']).join(', ')}`
+  queries.push({contents, callback, loading: false, fields: exprs, source, componentId})
   runAll()
   return componentId
 }
@@ -147,7 +145,7 @@ export function translateData(data: any, node: QueryNode): QueryResult {
   let rows = data.rows || []
   let fields: Field[] = []
 
-  let requestFields = Array.from(node.fields.values()).flatMap(f => f)
+  let requestFields = node.fields
 
   data.fields.forEach((field, index) => {
     let requested = requestFields[index]

package/dist/ui/internal/runSocket.ts

@@ -42,17 +42,14 @@ function connect() {
   socket.onopen = () => socket!.send(JSON.stringify({type: 'register', url: window.location.href}))
 
   socket.onmessage = async event => {
-    let {type, requestId, action, chart} = JSON.parse(event.data)
-    if (type !== 'check') return
+    let {requestId, action, chart} = JSON.parse(event.data)
+    let finished = await window.$GRAPHENE.waitForLoad(20_000)
 
     if (action === 'list') {
-      await window.$GRAPHENE.pageReady
-      await new Promise(resolve => requestAnimationFrame(resolve))
       socket!.send(JSON.stringify({type: 'checkResponse', requestId, componentIds: listComponentIds()}))
       return
     }
 
-    let finished = await window.$GRAPHENE.waitForLoad(20_000)
     let screenshot = chart ? await captureChart(chart) : await takeScreenshot()
     socket!.send(JSON.stringify({type: 'checkResponse', requestId, errors: getErrors(), stillLoading: !finished, screenshot}))
   }

package/dist/ui/internal/sidebar.svelte.js

@@ -1,4 +1,4 @@
-let state = $state({ open: false });
+let state = $state({ open: false, pinned: false });
 let closeTimer;
 const sidebar = {
   get open() {
@@ -10,7 +10,17 @@ const sidebar = {
   },
   leave() {
     clearTimeout(closeTimer);
+    if (state.pinned) return;
     closeTimer = setTimeout(() => state.open = false, 120);
+  },
+  pin() {
+    clearTimeout(closeTimer);
+    state.pinned = true;
+    state.open = true;
+  },
+  unpin() {
+    state.pinned = false;
+    this.leave();
   }
 };
 export {

package/dist/ui/web.js

@@ -41,6 +41,7 @@ import LocalApp from './internal/LocalApp.svelte'
 // code only has to load once.
 // In theory we could do this with Vite splitting, but then we have a hard dependency on the exact format vite uses. Plus I find the easier to understand.
 window.$GRAPHENE = window.$GRAPHENE || {}
+window.$GRAPHENE.appLoading = false
 
 let nextRenderId = 0
 let pendingRenders = new Set()
@@ -64,11 +65,11 @@ window.$GRAPHENE.waitForLoad = async (timeout = 20_000) => {
   let g = window.$GRAPHENE
   let end = Date.now() + timeout
   while (Date.now() < end) {
-    if (!g.isQueryLoading() && pendingRenders.size == 0) {
+    if (!g.appLoading && !g.isQueryLoading() && pendingRenders.size == 0) {
       if (document.fonts?.ready) await document.fonts.ready
       await new Promise(resolve => setTimeout(resolve, 300))
       await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))
-      if (!g.isQueryLoading() && pendingRenders.size == 0) return true
+      if (!g.appLoading && !g.isQueryLoading() && pendingRenders.size == 0) return true
     }
     await new Promise(resolve => setTimeout(resolve, 100))
   }
@@ -109,5 +110,6 @@ window.$GRAPHENE.components = {
 window.$GRAPHENE.svelte = {mount, unmount}
 
 if (window.location.pathname.replace(/\/+$/, '') !== '/__ct') {
+  window.$GRAPHENE.appLoading = true
   mount(LocalApp, {target: document.body})
 }