@malloydata/malloyyo 0.2.11 → 0.2.13

package/dist/index.js

@@ -62,82 +62,6 @@ function resolveInstance(dir, arg) {
 import { readFileSync as readFileSync2, existsSync as existsSync2, readdirSync, statSync } from "node:fs";
 import { join as join2, relative, sep } from "node:path";
 import { execFileSync } from "node:child_process";
-var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git"]);
-function gatherDirectory(dir) {
-  const files = [];
-  const walk = (cur) => {
-    for (const entry of readdirSync(cur)) {
-      if (entry.startsWith(".") || SKIP_DIRS.has(entry)) continue;
-      const full = join2(cur, entry);
-      if (statSync(full).isDirectory()) {
-        walk(full);
-      } else if (entry.endsWith(".malloy")) {
-        files.push({
-          path: relative(dir, full).split(sep).join("/"),
-          content: readFileSync2(full, "utf8")
-        });
-      }
-    }
-  };
-  walk(dir);
-  const configPath = join2(dir, "malloy-config.json");
-  const config = existsSync2(configPath) ? readFileSync2(configPath, "utf8") : void 0;
-  return { files, config };
-}
-function listDashboardDirs(dir) {
-  const base = join2(dir, "dashboards");
-  if (!existsSync2(base)) return [];
-  return readdirSync(base).filter((name) => {
-    const d = join2(base, name);
-    return statSync(d).isDirectory() && existsSync2(join2(d, "manifest.json"));
-  }).sort();
-}
-function gatherDashboards(dir) {
-  const base = join2(dir, "dashboards");
-  return listDashboardDirs(dir).map((name) => {
-    const raw = readFileSync2(join2(base, name, "manifest.json"), "utf8");
-    let manifest;
-    try {
-      manifest = JSON.parse(raw);
-    } catch (e) {
-      throw new Error(`dashboards/${name}/manifest.json: invalid JSON (${e.message})`);
-    }
-    const tsxPath = join2(base, name, "Dashboard.tsx");
-    if (!existsSync2(tsxPath)) throw new Error(`dashboards/${name}: missing Dashboard.tsx`);
-    return { name, manifest, source: readFileSync2(tsxPath, "utf8") };
-  });
-}
-function gitInfo(dir) {
-  const git = (args) => execFileSync("git", args, {
-    cwd: dir,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"]
-    // suppress git's own stderr (e.g. "no remote 'origin'")
-  }).trim();
-  try {
-    let repo;
-    try {
-      repo = git(["remote", "get-url", "origin"]).replace(
-        /^.*[:/]([^/]+\/[^/]+?)(?:\.git)?$/,
-        "$1"
-      );
-    } catch {
-    }
-    return {
-      repo,
-      branch: git(["rev-parse", "--abbrev-ref", "HEAD"]),
-      sha: git(["rev-parse", "HEAD"]),
-      dirty: git(["status", "--porcelain"]).length > 0
-    };
-  } catch {
-    return {};
-  }
-}
-
-// src/lint.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
-import { join as join3, resolve } from "node:path";
-import * as esbuild from "esbuild";
 
 // src/host.ts
 import fs from "node:fs";
@@ -1135,6 +1059,146 @@ async function runRestricted(runtime, entry, query, opts = {}) {
     return { ok: false, problems: [...loadProblems, errorProblem(e, entry.href)] };
   }
 }
+function renderGivenType2(t) {
+  if (t.type === "filter expression") {
+    return t.filterType ? `filter<${t.filterType}>` : "filter";
+  }
+  if (t.type === "array") {
+    const elem = t.elementTypeDef;
+    if (!elem) return "array";
+    if (elem.type === "record_element") return "record[]";
+    return `${renderGivenType2(elem)}[]`;
+  }
+  return t.type;
+}
+function defaultValue(e) {
+  if (!e) return void 0;
+  switch (e.node) {
+    case "filterLiteral":
+      return e.filterSrc;
+    case "stringLiteral":
+      return e.literal;
+    case "numberLiteral":
+      return Number(e.literal);
+    case "true":
+      return true;
+    case "false":
+      return false;
+    case "dateLiteral":
+    case "timestampLiteral":
+    case "timestamptzLiteral":
+      return e.literal;
+    default:
+      return void 0;
+  }
+}
+function describeGivenSpec(name, g) {
+  const spec = { name, type: renderGivenType2(g.type) };
+  if (g.type.type === "filter expression" && g.type.filterType) {
+    spec.filterType = g.type.filterType;
+  }
+  const dflt = defaultValue(g.default);
+  if (dflt !== void 0) spec.default = dflt;
+  try {
+    const docs = g.annotations.forRoute('"').map((n) => n.content.trim()).filter(Boolean);
+    if (docs.length) spec.description = docs.join("\n");
+  } catch {
+  }
+  try {
+    const dict = g.annotations.parseAsTag().tag.dict ?? {};
+    const tags = {};
+    for (const [key, t] of Object.entries(dict)) {
+      const eq = t.eq;
+      if (typeof eq === "string" || typeof eq === "number" || typeof eq === "boolean") {
+        tags[key] = eq;
+      } else if (eq === void 0 && !t.dict) {
+        tags[key] = true;
+      }
+    }
+    if (Object.keys(tags).length) spec.tags = tags;
+    const suggestDict = dict.suggest?.dict;
+    if (suggestDict) {
+      const suggest = {};
+      for (const key of ["source", "dimension", "query"]) {
+        const eq = suggestDict[key]?.eq;
+        if (typeof eq === "string") suggest[key] = eq;
+      }
+      if (suggest.source || suggest.query) spec.suggest = suggest;
+    }
+  } catch {
+  }
+  return spec;
+}
+async function dashboardGivenSpecs(runtime, entry, queryName) {
+  try {
+    const mm = runtime.loadModel(entry);
+    const model = await mm.getModel();
+    const named = [...model.queries().named];
+    if (!named.includes(queryName)) {
+      return {
+        ok: false,
+        error: `no query named '${queryName}' (model has: ${named.join(", ") || "none"})`
+      };
+    }
+    const pq = await mm.loadQueryByName(queryName).getPreparedQuery();
+    const specs = [];
+    for (const [name, g] of pq.givens) {
+      specs.push(describeGivenSpec(name, g));
+    }
+    return { ok: true, givens: specs };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+function docText(t) {
+  try {
+    const docs = t.annotations.forRoute('"').map((n) => n.content.trim()).filter(Boolean);
+    return docs.length ? docs.join("\n") : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readArtifactTag(queryName, q) {
+  let tag;
+  try {
+    tag = q.annotations.parseAsTag().tag;
+  } catch {
+    return void 0;
+  }
+  if (!tag.has("artifact")) return void 0;
+  const nested = tag.tag("artifact");
+  const description = docText(q);
+  const name = nested?.text("name") ?? tag.text("name") ?? queryName;
+  const title = nested?.text("title") ?? tag.text("title") ?? description?.split("\n")[0] ?? queryName;
+  const info = { name, query: queryName, title };
+  if (description) info.description = description;
+  const givensTag = tag.tag("artifact", "givens");
+  if (givensTag) {
+    const givens = {};
+    for (const [key, t] of Object.entries(givensTag.dict ?? {})) {
+      const eq = t.eq;
+      if (typeof eq === "string" || typeof eq === "number" || typeof eq === "boolean") {
+        givens[key] = eq;
+      }
+    }
+    if (Object.keys(givens).length) info.givens = givens;
+  }
+  return info;
+}
+async function artifactQueries(runtime, entry) {
+  try {
+    const model = await runtime.loadModel(entry).getModel();
+    const artifacts = [];
+    for (const queryName of model.queries().named) {
+      const pq = model.getPreparedQueryByName(queryName);
+      const info = readArtifactTag(queryName, pq);
+      if (info) artifacts.push(info);
+    }
+    return { ok: true, artifacts };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
 var INSTANCE_PLACEHOLDER = "{{INSTANCE_NAME}}";
 function renderInstructions(text, instanceName) {
   return text.replaceAll(INSTANCE_PLACEHOLDER, instanceName);
@@ -1621,6 +1685,25 @@ async function makeRunner(root) {
         (runtime, entry) => run(runtime, entry, { name: queryName, givens, stableResult: true, rowLimit: 5e3 })
       );
     },
+    runText(malloy, givens) {
+      return lease(
+        (runtime, entry) => runRestricted(runtime, entry, malloy, { givens, stableResult: true, rowLimit: 5e3 })
+      );
+    },
+    validateText(malloy) {
+      return lease(async (runtime, entry) => {
+        const v = await validateRestricted(runtime, entry, malloy);
+        if (v.ok) return { ok: true };
+        const msg = v.problems.filter((p) => p.severity === "error").map((p) => p.message).join("; ");
+        return { ok: false, error: msg || "restricted query failed to compile" };
+      });
+    },
+    givensForQuery(queryName) {
+      return lease((runtime, entry) => dashboardGivenSpecs(runtime, entry, queryName));
+    },
+    artifacts() {
+      return lease((runtime, entry) => artifactQueries(runtime, entry));
+    },
     validate(queryName, givens) {
       return lease(async (runtime, entry) => {
         try {
@@ -1642,51 +1725,138 @@ async function makeRunner(root) {
   };
 }
 
+// src/gather.ts
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+function gatherDirectory(dir) {
+  const files = [];
+  const walk = (cur) => {
+    for (const entry of readdirSync(cur)) {
+      if (entry.startsWith(".") || SKIP_DIRS.has(entry)) continue;
+      const full = join2(cur, entry);
+      if (statSync(full).isDirectory()) {
+        walk(full);
+      } else if (entry.endsWith(".malloy")) {
+        files.push({
+          path: relative(dir, full).split(sep).join("/"),
+          content: readFileSync2(full, "utf8")
+        });
+      }
+    }
+  };
+  walk(dir);
+  const configPath = join2(dir, "malloy-config.json");
+  const config = existsSync2(configPath) ? readFileSync2(configPath, "utf8") : void 0;
+  return { files, config };
+}
+function listDashboardDirs(dir) {
+  const base = join2(dir, "dashboards");
+  if (!existsSync2(base)) return [];
+  return readdirSync(base).filter((name) => statSync(join2(base, name)).isDirectory()).sort();
+}
+async function gatherDashboards(dir) {
+  const runner = await makeRunner(dir);
+  const res = await runner.artifacts();
+  if (!res.ok) throw new Error(`model error: ${res.error}`);
+  return res.artifacts.map((a) => {
+    const tsxPath = join2(dir, "dashboards", a.name, "Dashboard.tsx");
+    const manifest = { title: a.title, query: a.query };
+    if (a.description) manifest.description = a.description;
+    if (a.givens) manifest.givens = a.givens;
+    return {
+      name: a.name,
+      manifest,
+      source: existsSync2(tsxPath) ? readFileSync2(tsxPath, "utf8") : ""
+    };
+  });
+}
+function gitInfo(dir) {
+  const git = (args) => execFileSync("git", args, {
+    cwd: dir,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+    // suppress git's own stderr (e.g. "no remote 'origin'")
+  }).trim();
+  try {
+    let repo;
+    try {
+      repo = git(["remote", "get-url", "origin"]).replace(
+        /^.*[:/]([^/]+\/[^/]+?)(?:\.git)?$/,
+        "$1"
+      );
+    } catch {
+    }
+    return {
+      repo,
+      branch: git(["rev-parse", "--abbrev-ref", "HEAD"]),
+      sha: git(["rev-parse", "HEAD"]),
+      dirty: git(["status", "--porcelain"]).length > 0
+    };
+  } catch {
+    return {};
+  }
+}
+
 // src/lint.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { join as join3, resolve } from "node:path";
+import * as esbuild from "esbuild";
+var quoteField = (f) => /^[A-Za-z_]\w*$/.test(f) ? f : `\`${f}\``;
 async function lintDashboards(root) {
   const abs = resolve(root);
-  const names = listDashboardDirs(abs);
   const dashboards = [];
-  if (names.length === 0) return { ok: true, dashboards };
   const runner = await makeRunner(abs);
   if (!runner.entryExists()) {
     return { ok: false, dashboards: [{ name: "(model)", errors: [`no index.malloy at ${abs}`] }] };
   }
-  for (const name of names) {
+  const arts = await runner.artifacts();
+  if (!arts.ok) {
+    return { ok: false, dashboards: [{ name: "(model)", errors: [arts.error] }] };
+  }
+  const artifacts = arts.artifacts;
+  const dirs = listDashboardDirs(abs);
+  if (artifacts.length === 0 && dirs.length === 0) return { ok: true, dashboards };
+  const declared = new Set(artifacts.map((a) => a.name));
+  for (const dir of dirs) {
     const errors = [];
-    const dir = join3(abs, "dashboards", name);
-    let manifest = null;
-    try {
-      manifest = JSON.parse(readFileSync3(join3(dir, "manifest.json"), "utf8"));
-    } catch (e) {
-      errors.push(`manifest.json: invalid JSON (${e.message})`);
-    }
-    let query;
-    const givenValues = {};
-    if (manifest) {
-      if (typeof manifest.title !== "string") errors.push(`manifest: "title" must be a string`);
-      if (typeof manifest.query !== "string") errors.push(`manifest: "query" must be a string`);
-      else query = manifest.query;
-      const givens = manifest.givens;
-      if (!Array.isArray(givens)) {
-        errors.push(`manifest: "givens" must be an array`);
-      } else {
-        for (const g of givens) {
-          if (typeof g?.name !== "string") {
-            errors.push(`manifest: every given needs a string "name"`);
-            continue;
-          }
-          if (g.type !== "string" && g.type !== "number" && g.type !== "boolean") {
-            errors.push(`given "${g.name}": "type" must be "string", "number", or "boolean"`);
-          }
-          if (g.default !== void 0) givenValues[g.name] = g.default;
+    if (existsSync3(join3(abs, "dashboards", dir, "manifest.json"))) {
+      errors.push(
+        `manifest.json is obsolete \u2014 delete it; the model's \`# artifact title="\u2026"\` tag on the query is the manifest now`
+      );
+    }
+    if (!declared.has(dir)) {
+      errors.push(
+        `no query is tagged for this dashboard \u2014 tag one with \`# artifact\` (or \`# artifact name="${dir}"\`) in the model`
+      );
+    }
+    if (errors.length) dashboards.push({ name: dir, errors });
+  }
+  for (const artifact of artifacts) {
+    const errors = [];
+    const v = await runner.validate(artifact.query, {});
+    if (!v.ok) errors.push(v.error);
+    const specs = await runner.givensForQuery(artifact.query);
+    if (specs.ok) {
+      for (const spec of specs.givens) {
+        if (spec.tags?.suggest_query !== void 0) {
+          errors.push(
+            `given "${spec.name}": suggest_query is obsolete \u2014 declare # suggest { source=\u2026 dimension=\u2026 } or # suggest { query=\u2026 }`
+          );
+        }
+        const suggest = spec.suggest;
+        if (!suggest) continue;
+        const base = suggest.query ? `run: ${suggest.query}` : suggest.source && suggest.dimension ? `run: ${suggest.source} -> ${quoteField(suggest.dimension)}` : null;
+        if (base === null) {
+          errors.push(
+            `given "${spec.name}": suggest must be \`suggest { source=<source> dimension=<field> }\` or \`suggest { query=<named_query> [dimension=<field>] }\``
+          );
+          continue;
         }
+        const sv = await runner.validateText(base);
+        if (!sv.ok) errors.push(`given "${spec.name}": suggest does not compile \u2014 ${sv.error}`);
       }
     }
-    const tsxPath = join3(dir, "Dashboard.tsx");
-    if (!existsSync3(tsxPath)) {
-      errors.push(`missing Dashboard.tsx`);
-    } else {
+    const tsxPath = join3(abs, "dashboards", artifact.name, "Dashboard.tsx");
+    if (existsSync3(tsxPath)) {
       try {
         await esbuild.transform(readFileSync3(tsxPath, "utf8"), { loader: "tsx", jsx: "automatic" });
       } catch (e) {
@@ -1694,11 +1864,7 @@ async function lintDashboards(root) {
         errors.push(`Dashboard.tsx: ${msg}`);
       }
     }
-    if (query) {
-      const v = await runner.validate(query, givenValues);
-      if (!v.ok) errors.push(v.error);
-    }
-    dashboards.push({ name, errors });
+    dashboards.push({ name: artifact.name, errors });
   }
   return { ok: dashboards.every((d) => d.errors.length === 0), dashboards };
 }
@@ -1998,59 +2164,247 @@ var DASHBOARD_GUIDANCE = `
 
 # Authoring dashboards
 
-You can build a **dashboard** for this model: a small React view that renders one
-or more of the model's queries, with filter controls. Store it in the repo under
-\`./dashboards/<name>/\`. Preview it with \`malloyyo dashboard dev\`.
+A dashboard is DECLARED IN THE MODEL \u2014 there is no manifest file and, for the
+basic case, no JavaScript at all. Preview with \`malloyyo dashboard dev\`; check
+with \`malloyyo lint\`.
+
+## Make dashboards discoverable: the entry model
 
-## Before you write anything
-1. Call \`describe_source\` to see the model's **named queries** and its
-   **givens** (the declared filter inputs, e.g. STATE, DECADE, with their types).
-   A dashboard may ONLY run named queries the model exposes, driven by givens \u2014
-   never invent Malloy in the dashboard.
-2. If the query or givens you need don't exist yet, add them to the \`.malloy\`
-   model first (a top-level \`query:\` that references \`$GIVEN\` in its filters),
-   then re-check with \`describe_source\`.
+**The entry is \`index.malloy\`.** \`dashboard dev\`, \`lint\`, and the hosted
+server only see what that file EXPORTS. Three things must all be surfaced
+(imported AND exported) through it, or the feature looks broken:
 
-## Files to create
-\`./dashboards/<name>/manifest.json\`
-\`\`\`json
-{
-  "title": "Human title",
-  "query": "<a named query from the model>",
-  "givens": [
-    { "name": "STATE",  "label": "State",  "type": "string", "control": "select",
-      "options": ["CA","NY","TX"], "default": "CA" },
-    { "name": "DECADE", "label": "Decade", "type": "number", "control": "select",
-      "options": [1980,1990], "default": 1980 }
-  ]
+1. **The \`# artifact\`-tagged queries.** Declared in another file and not
+   exported \u2192 \`dashboard dev\` says "No dashboards declared" and \`lint\` says
+   "no dashboards to lint", even though the model compiles clean.
+2. **Every filter given the dashboards reference.** An unexported given
+   silently resolves to its declaration default \u2014 the control still renders
+   but CAN'T CHANGE THE QUERY (the filter looks inert).
+3. **Whatever backs each \`suggest\`** \u2014 the named query (\`suggest {query=\u2026}\`)
+   or source (\`suggest {source=\u2026}\`). Suggestions run against the entry model;
+   an unexported one fails lint with "Reference to undefined object".
+
+\`\`\`malloy
+##! experimental.givens
+import {
+  order_items,
+  BRAND, CATEGORY, PERIOD,          // the filter givens
+  brand_suggest,                    // backs a suggest {query=\u2026}
+  overview_dashboard                // the # artifact query
+} from 'ecommerce.malloy'
+export { order_items, BRAND, CATEGORY, PERIOD, brand_suggest, overview_dashboard }
+\`\`\`
+
+Prefer \`suggest { query=<named-query> \u2026 }\` over \`suggest { source=\u2026 }\` for
+anything beyond a throwaway: you export one small governed query instead of a
+whole base source.
+
+## The model is the whole contract
+
+**1. Tag a top-level query** with \`# artifact\` to declare a dashboard. For
+the common overview shape (top-level aggregates + nests), ALSO tag it
+\`# dashboard\` so the result renders as KPI tiles + a card grid instead of one
+flat table \u2014 they're partners: \`# artifact\` declares the dashboard,
+\`# dashboard\` is the renderer tag that draws it like one:
+
+\`\`\`malloy
+#" Business health at a glance \u2014 sales, margin, orders.
+# artifact { title="Business Overview" } dashboard
+query: overview_dashboard is order_items -> {
+  where:
+    inventory_items.product_brand ~ $BRAND,     // multi-filter where: is
+    inventory_items.product_category ~ $CATEGORY,  // COMMA separated
+    created_at ~ $PERIOD
+  aggregate: total_sales, total_gross_margin, order_count
+  nest:
+    # line_chart
+    sales_trend is by_month
+    top_brands
+    # shape_map
+    sales_by_state
 }
 \`\`\`
-Given \`name\`s must match the model's given names exactly; \`type\` must match.
 
-\`./dashboards/<name>/Dashboard.tsx\` \u2014 a default-exported React component. It
-receives everything as props from the host runtime; it must NOT import data
-libraries, fetch, or hold credentials:
+That's a complete dashboard: the runtime auto-renders a title (the tag's
+\`title\`, else the \`#"\` doc comment), a control for every given the query
+references, and the result panel. \`name="slug"\` overrides the URL/directory
+slug (default: the query name). Note the \`where:\` clauses applying givens are
+COMMA-separated \u2014 newline-separated conditions do not parse.
+
+Two dashboards can share a given but start on different values \u2014 a \`givens\`
+block in the tag sets PER-DASHBOARD defaults (given values, i.e. filter
+expressions; URL params still win):
+
+\`\`\`malloy
+# artifact { name="manufacturer" title="Manufacturer Recall Profile" givens { MANUFACTURER="Ford Motor Company" } }
+\`\`\`
+
+This replaces the "declare the given's default per dashboard" role the old
+manifests had: declare the given once with a neutral default (often \`f''\` =
+no filter), and let each tag pick its landing state.
+
+**2. Declare the filters as \`filter<T>\` givens** \u2014 never raw strings/numbers.
+A \`filter<string>\` value accepts one value ('NY'), alternatives ('NY, CA'),
+wildcards ('Ann%'), negation ('-NY'); a \`filter<number>\` accepts ranges
+('[1910 to 1930]') and comparisons ('> 200'); a \`filter<timestamp>\` /
+\`filter<date>\` accepts relative windows ('7 days' = the last 7 days, 'today',
+'last month') and literal ranges ('2026-01-01 to 2026-07-01' \u2014 NO \`@\` in
+filter literals). Apply with \`~\`; \`f''\` = empty = no filter (the natural
+"All"/"all time" \u2014 just \`col ~ $X\`, no \`$X = '' or \u2026\` dance):
+
+\`\`\`malloy
+##! experimental { givens }
+given:
+  # label="State" control=select suggest { source=baby_names dimension=state }
+  STATE :: filter<string> is f'NY'
+  # label="Brand" suggest { query=brand_suggest dimension=product_brand }
+  BRAND :: filter<string> is f''
+  # label="Years" range_min=1910 range_max=2025
+  YEAR_RANGE :: filter<number> is f'[1910 to 1930]'
+  # label="Time period"
+  PERIOD :: filter<timestamp> is f''
+  # label="Include rare names"
+  INCLUDE_RARE :: boolean is false
+\`\`\`
+
+Tags on the declaration drive the control (tag syntax is \`key="value"\` \u2014
+equals, not colon):
+- \`label\` \u2014 control caption (defaults to the given's name)
+- \`suggest { \u2026 }\` \u2014 where the control's options come from. NO Malloy code in
+  strings \u2014 just names:
+  - \`suggest { query=brand_suggest dimension=product_brand }\` \u2014 the FIRST
+    COLUMN of a named query (declare the query in the model \u2014 governed,
+    reviewable, and only that query needs exporting). PREFER THIS FORM.
+  - \`suggest { source=baby_names dimension=state }\` \u2014 the DISTINCT VALUES of
+    a dimension on a source (the whole source must be exported)
+  A \`dimension\` (in either form) is what enables SERVER-SIDE TYPEAHEAD: the
+  runtime refines the base query with what the user has typed
+  (\`\u2026 + { where: lower(field) ~ f'll%'; limit: 50 }\`, case-insensitive,
+  escaped). Without a dimension the fetched list is filtered client-side.
+  Runs as a restricted query; lint checks the declaration compiles.
+
+  **RELATED (faceted) filters** \u2014 query-form only: a suggest query may
+  reference the OTHER givens, and the runtime runs it with the dashboard's
+  current values (the suggested given itself is excluded, so the list never
+  collapses to the current pick). Brand suggestions narrow when Category is
+  set:
+
+  \`\`\`malloy
+  query: brand_suggest is inventory_items -> product_brand + {
+    where:
+      product_category ~ $CATEGORY,      // NOT product_brand ~ $BRAND
+      product_department ~ $DEPARTMENT
+    limit: 500
+  }
+  \`\`\`
+
+  Declare one \`*_suggest\` per filter, each referencing the others; \`f''\`
+  defaults mean unset filters don't constrain. \`source=\` suggests can't do
+  this (no place for a \`where:\`) \u2014 another reason to prefer \`query=\`.
+- \`control=select\` \u2014 a fixed dropdown instead of a typeahead search box
+- \`range_min\` / \`range_max\` \u2014 bounds; makes a filter<number> given a
+  dual-thumb range slider
+- anything else passes through in \`spec.tags\` for custom components
+
+Control picked from the declaration automatically: numeric range tags \u2192
+dual-thumb slider; \`filter<timestamp|timestamptz|date>\` \u2192 the TimeRange
+widget (relative presets: Today / Last 7 days / Last 30 days / \u2026 plus a
+"Custom range\u2026" from/to date picker); suggest + control=select \u2192 dropdown;
+boolean \u2192 checkbox; anything else \u2192 committing search box with typeahead.
+The suggest-driven options are DATA VALUES only \u2014 options that aren't column
+values (custom time presets, threshold buckets) need a custom component
+(below) with explicit \`{value, text}\` options where value is a filter
+expression built with \`filters.*\`.
+
+## Custom components (optional): ./dashboards/<slug>/Dashboard.tsx
+
+When the default UI isn't enough, add ONE file. It composes the runtime's
+widgets/hooks with your own React \u2014 you own layout, copy, and theming; the
+model still owns every query and filter:
+
 \`\`\`tsx
-export default function Dashboard({ manifest, givens, setGiven, Panel }) {
-  // givens   : current filter values, e.g. { STATE: "CA", DECADE: 1980 }
-  // setGiven : (name, value) => void  \u2014 change a filter, the Panel re-runs
-  // Panel    : <Panel givens={givens} /> runs manifest.query with those givens
-  //            and renders the result with Malloy's renderer
-  // Lay out the controls + Panel however you like \u2014 this is your React.
+import React from "react";
+import { Controls, Given, Search, Select, TimeRange, Panel, filters, useGiven } from "@malloyyo/dashboard";
+
+export default function Dashboard({ dashboard, givens }) {
+  return (
+    <div style={{ maxWidth: 860, margin: "0 auto", padding: 24 }}>
+      <h1>{dashboard.title}</h1>
+      <Controls>
+        <Given name="STATE" />          {/* picks the control from the declaration */}
+        <Search given="NAME" />         {/* committing input + typeahead + validation */}
+        <TimeRange given="PERIOD" presets={[
+          { value: "", text: "All time" },
+          { value: filters.lastN(1, "day"), text: "Last day" },
+          { value: filters.lastN(1, "week"), text: "Last week" },
+          { value: filters.lastN(1, "month"), text: "Last month" },
+        ]} />                            {/* "Custom range\u2026" is always appended */}
+        <Select given="MIN_SAMPLE"
+          options={[10, 200, 1000].map(n => ({ value: filters.greaterThan(n), text: \`> \${n}\` }))} />
+      </Controls>
+      <Panel givens={givens} />         {/* the tagged query, Malloy renderer */}
+      <Panel malloy="baby_names -> births_by_decade" givens={givens} />  {/* restricted text */}
+    </div>
+  );
 }
 \`\`\`
 
+From \`@malloyyo/dashboard\` (also handed to the component as props):
+- **Widgets** (headless-ish; restyle via className/style or CSS vars
+  \`--dash-fg/-muted/-border/-accent/-control-bg/-controls-bg\`):
+  \`<Controls/>\` (all givens, or compose children), \`<Given name/>\`,
+  \`<Select given [options]/>\`, \`<Search given/>\`, \`<Range given [min max]/>\`,
+  \`<TimeRange given [presets]/>\` (temporal presets + custom range),
+  \`<Checkbox given/>\` (bound to a boolean given)
+- **Hooks**: \`useGiven(name)\` \u2192 {value, set, spec};
+  \`useOptions(name, typed?)\` \u2192 {options, loading} (typeahead);
+  \`useQuery({query|malloy, givens})\` \u2192 {rows, loading, error} \u2014 plain rows
+  for your own visuals
+- **Helpers**: \`filters.oneOf/contains/between/atLeast/\u2026\` build
+  filter-expression strings with correct escaping; temporal:
+  \`filters.lastN(7, "day")\` \u2192 \`'7 days'\`, \`filters.dateRange("2026-01-01",
+  "2026-07-01")\`, \`filters.afterDate/beforeDate\`; read back with
+  \`filters.values/numberRange/threshold/inLast/temporalRange\`;
+  \`filters.isValid(type, src)\` checks typed input.
+  Never hand-concatenate a filter string.
+  **Escaping rule for custom controls:** a filter given's value is an
+  EXPRESSION, so committing a raw column value is wrong the moment it contains
+  a comma/percent/dash ('Tesla, Inc.' parses as two alternatives and matches
+  nothing). Commit \`filters.oneOf(value)\` (exact) or
+  \`filters.contains(term)\` (substring), and unwrap for display with
+  \`filters.values(src)\`. The stock \`<Select/>\` does this automatically;
+  \`<Search/>\` deliberately commits raw text (its input IS a filter
+  expression).
+- \`<Panel/>\` and \`runData(text, givens)\` \u2014 named queries are the primary
+  form; arbitrary Malloy runs as a RESTRICTED query (no import / given: /
+  connection.* / raw SQL / ##! flags \u2014 the model's published surface only).
+
 ## Rules
-- Only React is available to the dashboard (plus the injected \`Panel\`). No other
-  imports, no network, no arbitrary Malloy \u2014 the runtime sandboxes it.
-- Interactivity is done by changing **givens** (which drive the query's filters),
-  not by rewriting queries.
-- The dashboard runs against the SAME model you're exploring, so what you preview
-  is what the model actually returns.
+- Declare data in the model: givens are \`filter<T>\`, options come from
+  \`# suggest {\u2026}\` declarations, dashboards are \`# artifact\` tags. If a query or given you
+  need is missing, add it to the \`.malloy\` file first (check with
+  \`describe_source\`).
+- Surface everything through the entry model (see the top section).
+- Only React + \`@malloyyo/dashboard\` are importable. No other imports, no
+  network \u2014 the runtime sandboxes the component.
+- Interactivity = setting given values (filter-expression strings), not
+  rewriting query text per interaction.
 
-## Preview
-From the model repo: \`malloyyo dashboard dev\` \u2192 open the printed URL. Editing
-\`Dashboard.tsx\` and reloading rebuilds it.
+## Preview & validate
+\`malloyyo dashboard dev\` \u2192 open the printed URL. Edits to \`.malloy\` (tags,
+givens, queries) and \`Dashboard.tsx\` hot-reload. \`malloyyo lint\` validates
+the tagged queries, given \`suggest\` declarations, and any Dashboard.tsx \u2014
+but only for dashboards REACHABLE FROM THE ENTRY: "no dashboards to lint"
+usually means the \`# artifact\` queries aren't exported through
+\`index.malloy\`, not that they don't exist.
+
+Validation loop that works well: the local \`malloyyo mcp\` server hot-reloads
+working-directory edits \u2014 \`query(execute:false)\` to compile-check,
+\`execute:true\` to run. A top-level \`# artifact\` query runs as
+\`run: <name>\` (not \`source -> <name>\`), and is only visible once exported
+through the entry. Don't validate local edits against a hosted/claude.ai
+connector \u2014 that serves the PUBLISHED model, which is stale until
+\`malloyyo publish\`.
 `;
 
 // src/mcp.ts
@@ -2184,7 +2538,8 @@ var HOST_LIBS = [
   "react-dom/client",
   "react/jsx-runtime",
   "react/jsx-dev-runtime",
-  "@malloydata/render"
+  "@malloydata/render",
+  "@malloydata/malloy-filter"
 ];
 var HOST_ALIAS = {};
 for (const spec of HOST_LIBS) {
@@ -2193,46 +2548,41 @@ for (const spec of HOST_LIBS) {
   } catch {
   }
 }
-function resolveFrameEntry() {
+function resolveRuntimeDir() {
   const candidates = [
-    new URL("./frame-entry.tsx", import.meta.url),
+    new URL("./frame-runtime/", import.meta.url),
     // dev: src/dashboard.ts
-    new URL("../src/frame-entry.tsx", import.meta.url)
+    new URL("../src/frame-runtime/", import.meta.url)
     // built: dist/index.js
   ].map((u) => fileURLToPath(u));
   const found = candidates.find((c) => fs3.existsSync(c));
   if (!found) {
     throw new Error(
-      "frame-entry.tsx not found \u2014 `dashboard dev` currently needs the CLI source checkout (looked in ./ and ../src). See docs/repo-artifacts.md packaging note."
+      "frame-runtime/ not found \u2014 `dashboard dev` currently needs the CLI source checkout (looked in ./ and ../src). See docs/repo-artifacts.md packaging note."
     );
   }
   return found;
 }
-function discoverDashboards(root) {
-  const base = path4.join(root, "dashboards");
-  if (!fs3.existsSync(base)) return [];
-  const out = [];
-  for (const name of fs3.readdirSync(base)) {
-    const dir = path4.join(base, name);
-    const mf = path4.join(dir, "manifest.json");
-    if (!fs3.statSync(dir).isDirectory() || !fs3.existsSync(mf)) continue;
-    try {
-      out.push({ name, dir, manifest: JSON.parse(fs3.readFileSync(mf, "utf8")) });
-    } catch (e) {
-      console.error(`  ! skipping ${name}: bad manifest.json (${e.message})`);
-    }
-  }
-  return out.sort((a, b) => a.name.localeCompare(b.name));
+var resolveFrameEntry = () => path4.join(resolveRuntimeDir(), "..", "frame-entry.tsx");
+async function discoverDashboards(root, runner) {
+  const result = await runner.artifacts();
+  if (!result.ok) throw new Error(`model error: ${result.error}`);
+  return result.artifacts.map((a) => {
+    const tsxPath = path4.join(root, "dashboards", a.name, "Dashboard.tsx");
+    return { ...a, tsxPath: fs3.existsSync(tsxPath) ? tsxPath : void 0 };
+  });
 }
 var esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 function makeBundler() {
   const cache = /* @__PURE__ */ new Map();
   const frameEntry = resolveFrameEntry();
+  const runtimeDir = resolveRuntimeDir();
+  const runtimeIndex = path4.join(runtimeDir, "index.ts");
+  const runtimeStamp = () => fs3.statSync(frameEntry).mtimeMs + fs3.readdirSync(runtimeDir).map((f) => fs3.statSync(path4.join(runtimeDir, f)).mtimeMs).reduce((a, b) => a + b, 0);
   return async function bundle(dash) {
-    const dashboardFile = path4.join(dash.dir, "Dashboard.tsx");
-    const mtimeMs = fs3.statSync(dashboardFile).mtimeMs + fs3.statSync(frameEntry).mtimeMs;
+    const stamp = runtimeStamp() + (dash.tsxPath ? fs3.statSync(dash.tsxPath).mtimeMs : 0);
     const hit = cache.get(dash.name);
-    if (hit && hit.mtimeMs === mtimeMs) return hit.js;
+    if (hit && hit.stamp === stamp) return hit.js;
     const result = await esbuild2.build({
       entryPoints: [frameEntry],
       bundle: true,
@@ -2247,9 +2597,22 @@ function makeBundler() {
         {
           name: "virtual-dashboard",
           setup(b) {
-            b.onResolve({ filter: /^virtual:dashboard$/ }, () => ({ path: dashboardFile }));
+            if (dash.tsxPath) {
+              const tsxPath = dash.tsxPath;
+              b.onResolve({ filter: /^virtual:dashboard$/ }, () => ({ path: tsxPath }));
+            } else {
+              b.onResolve({ filter: /^virtual:dashboard$/ }, () => ({
+                path: "default-dashboard",
+                namespace: "vdefault"
+              }));
+              b.onLoad({ filter: /.*/, namespace: "vdefault" }, () => ({
+                contents: `export default null;`,
+                loader: "js"
+              }));
+            }
+            b.onResolve({ filter: /^@malloyyo\/dashboard$/ }, () => ({ path: runtimeIndex }));
             b.onResolve(
-              { filter: /^(react($|\/)|react-dom($|\/)|@malloydata\/render$)/ },
+              { filter: /^(react($|\/)|react-dom($|\/)|@malloydata\/(render|malloy-filter)$)/ },
               (args) => HOST_ALIAS[args.path] ? { path: HOST_ALIAS[args.path] } : void 0
             );
           }
@@ -2257,7 +2620,7 @@ function makeBundler() {
       ]
     });
     const js = result.outputFiles[0].text;
-    cache.set(dash.name, { mtimeMs, js });
+    cache.set(dash.name, { stamp, js });
     return js;
   };
 }
@@ -2268,7 +2631,7 @@ function parentShell(dash, frameBase, all, initialGivens) {
   const fb = JSON.stringify(frameBase);
   const nav = all.length > 1 ? `<nav style="display:flex;gap:4px;align-items:center;padding:8px 12px;background:#f6f7f9;border-bottom:1px solid #e2e4e8;font:13px system-ui,sans-serif"><span style="color:#888;margin-right:8px">Dashboards</span>` + all.map((x) => {
     const on = x.name === dash.name;
-    return `<a href="/?d=${encodeURIComponent(x.name)}" style="padding:4px 10px;border-radius:6px;text-decoration:none;${on ? "background:#1a1a1a;color:#fff" : "color:#333"}">${esc(x.manifest.title || x.name)}</a>`;
+    return `<a href="/?d=${encodeURIComponent(x.name)}" style="padding:4px 10px;border-radius:6px;text-decoration:none;${on ? "background:#1a1a1a;color:#fff" : "color:#333"}">${esc(x.title || x.name)}</a>`;
   }).join("") + `</nav>` : "";
   return html(
     `<div style="display:flex;flex-direction:column;height:100vh">` + nav + `<iframe id="f" sandbox="allow-scripts allow-same-origin" src="${frameBase}/frame?d=${encodeURIComponent(dash.name)}${givensQs}" style="border:0;flex:1;width:100%"></iframe></div><script>
@@ -2288,13 +2651,13 @@ window.addEventListener('message',async(e)=>{
   let out;
   try{
     const res=await fetch('/api/run',{method:'POST',headers:{'content-type':'application/json'},
-      body:JSON.stringify({d:${d},query:m.query,givens:m.givens})});
+      body:JSON.stringify({d:${d},query:m.query,malloy:m.malloy,givens:m.givens})});
     out=await res.json();
   }catch(err){ out={ok:false,problems:[{message:String(err)}]}; }
   f.contentWindow.postMessage({type:'result',id:m.id,...out},${fb});
 });
 </script>`,
-    dash.manifest.title
+    dash.title
   );
 }
 function givensFromUrl(url4) {
@@ -2302,10 +2665,17 @@ function givensFromUrl(url4) {
   for (const [k, v] of url4.searchParams) if (k !== "d") g[k] = v;
   return g;
 }
-function frameDoc(dash, initialGivens) {
+function frameDoc(dash, givenSpecs, initialGivens) {
+  const info = {
+    name: dash.name,
+    query: dash.query,
+    title: dash.title,
+    description: dash.description,
+    givens: dash.givens
+  };
   return html(
-    `<div id="root"></div><script>window.__MANIFEST__=${JSON.stringify(dash.manifest)};window.__INITIAL_GIVENS__=${JSON.stringify(initialGivens)}</script><script src="/bundle.js?d=${encodeURIComponent(dash.name)}"></script>`,
-    dash.manifest.title
+    `<div id="root"></div><script>window.__DASHBOARD__=${JSON.stringify(info)};window.__GIVENS__=${JSON.stringify(givenSpecs)};window.__INITIAL_GIVENS__=${JSON.stringify(initialGivens)}</script><script src="/bundle.js?d=${encodeURIComponent(dash.name)}"></script>`,
+    dash.title
   );
 }
 async function readBody(req) {
@@ -2319,15 +2689,17 @@ async function serveDashboard(opts) {
   const port = opts.port ?? 4173;
   const framePort = port + 1;
   const frameBase = `http://localhost:${framePort}`;
-  let dashboards = discoverDashboards(root);
-  if (dashboards.length === 0) {
-    throw new Error(`No dashboards found under ${path4.join(root, "dashboards")}/`);
-  }
-  let byName = new Map(dashboards.map((d) => [d.name, d]));
   const runner = await makeRunner(root);
   if (!runner.entryExists()) {
     throw new Error(`No index.malloy at ${root} \u2014 run this from a Malloy model repo.`);
   }
+  let dashboards = await discoverDashboards(root, runner);
+  if (dashboards.length === 0) {
+    throw new Error(
+      `No dashboards declared \u2014 tag a top-level query with \`# artifact title="\u2026"\` in the model.`
+    );
+  }
+  let byName = new Map(dashboards.map((d) => [d.name, d]));
   const bundle = makeBundler();
   const pick = (url4) => byName.get(url4.searchParams.get("d") ?? dashboards[0].name) ?? dashboards[0];
   const sseClients = /* @__PURE__ */ new Set();
@@ -2341,10 +2713,12 @@ async function serveDashboard(opts) {
       if (!f.endsWith(".malloy") && !f.includes("dashboards")) return;
       clearTimeout(debounce);
       debounce = setTimeout(() => {
-        dashboards = discoverDashboards(root);
-        byName = new Map(dashboards.map((d) => [d.name, d]));
-        console.error(`  \u21BB ${f} changed \u2014 reloading`);
-        notifyReload();
+        discoverDashboards(root, runner).then((next) => {
+          dashboards = next;
+          byName = new Map(dashboards.map((d) => [d.name, d]));
+          console.error(`  \u21BB ${f} changed \u2014 reloading`);
+          notifyReload();
+        }).catch((e) => console.error(`  ! model error after ${f} changed: ${e.message}`));
       }, 150);
     });
   } catch (e) {
@@ -2360,7 +2734,16 @@ async function serveDashboard(opts) {
     try {
       if (onFramePort) {
         if (url4.pathname === "/frame") {
-          return send(200, "text/html; charset=utf-8", frameDoc(pick(url4), givensFromUrl(url4)));
+          const dash = pick(url4);
+          const specs = await runner.givensForQuery(dash.query);
+          if (!specs.ok) {
+            return send(
+              200,
+              "text/html; charset=utf-8",
+              html(`<pre style="color:crimson;padding:16px">model error: ${esc(specs.error)}</pre>`, dash.title)
+            );
+          }
+          return send(200, "text/html; charset=utf-8", frameDoc(dash, specs.givens, givensFromUrl(url4)));
         }
         if (url4.pathname === "/bundle.js") {
           return send(200, "application/javascript; charset=utf-8", await bundle(pick(url4)));
@@ -2378,13 +2761,10 @@ async function serveDashboard(opts) {
         return send(200, "text/html; charset=utf-8", parentShell(pick(url4), frameBase, dashboards, givensFromUrl(url4)));
       }
       if (url4.pathname === "/api/run" && req.method === "POST") {
-        const { d, query, givens } = JSON.parse(await readBody(req));
+        const { d, query, malloy, givens } = JSON.parse(await readBody(req));
         const dash = byName.get(d);
         if (!dash) return send(404, "application/json", JSON.stringify({ ok: false, problems: [{ message: `no dashboard '${d}'` }] }));
-        if (query !== dash.manifest.query) {
-          return send(403, "application/json", JSON.stringify({ ok: false, problems: [{ message: `query '${query}' is not declared by ${d}` }] }));
-        }
-        const out = await runner.run(query, givens ?? {});
+        const out = typeof malloy === "string" ? await runner.runText(malloy, givens ?? {}) : await runner.run(String(query ?? dash.query), givens ?? {});
         return send(200, "application/json", JSON.stringify(out));
       }
       send(404, "text/plain", "not found");
@@ -2400,7 +2780,8 @@ async function serveDashboard(opts) {
   malloyyo dashboard dev \u2014 model: ${root}`);
   console.error(`  http://localhost:${port}/   (artifact origin: ${frameBase})`);
   for (const d of dashboards) {
-    console.error(`    \u2022 ${d.name}  \u2192  http://localhost:${port}/?d=${d.name}`);
+    const kind = d.tsxPath ? "custom" : "default UI";
+    console.error(`    \u2022 ${d.name} (${kind})  \u2192  http://localhost:${port}/?d=${d.name}`);
   }
   console.error(`  Ctrl-C to stop.
 `);
@@ -2409,7 +2790,7 @@ async function serveDashboard(opts) {
 }
 
 // package.json
-var version = "0.2.11";
+var version = "0.2.13";
 
 // src/index.ts
 function shortSha(sha) {
@@ -2434,7 +2815,7 @@ async function publish(target, dir, opts) {
     }
   }
   const git = gitInfo(root);
-  const dashboards = gatherDashboards(root);
+  const dashboards = await gatherDashboards(root);
   const body = { files, config, git, dashboards };
   const provenance = git.sha ? `${git.branch}@${shortSha(git.sha)}${git.dirty ? " (dirty)" : ""}` : "(no git)";
   console.log(`\u2192 ${t.url}  dataset=${t.dataset}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@malloydata/malloyyo",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Publish Malloy models to a Malloyyo instance",
   "license": "MIT",
   "repository": {
@@ -34,6 +34,7 @@
   "dependencies": {
     "@malloydata/malloy": "0.0.420",
     "@malloydata/malloy-connections": "0.0.420",
+    "@malloydata/malloy-filter": "0.0.420",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^12.1.0"
   },