malloy-html-data-apps

In-Package HTML Data Apps

A package becomes a web app by adding a public/ directory. Publisher serves those files and gives the page Publisher.query(...) to run Malloy against the package's models. No build step, no npm, no framework.

When this is the right tool

Pick an HTML data app when the user wants full control of the markup and only plain web files.

Package anatomy

my-package/
  publisher.json        # name, version, description
  subscriptions.malloy  # the model(s), stays private
  subscriptions.parquet # data, stays private
  public/               # ONLY this directory is web-served
    index.html
    app.js
    vendor/             # chart library, vendored rather than loaded from a CDN
      chart.umd.js

Only public/ is reachable over the web, at /environments/<env>/packages/<pkg>/<file>. Models, data, and publisher.json are private and reached only through the query API, which still applies the model's filters, access modifiers, and authorize rules. There is no flag to set: a public/ directory is what makes a package an app.

Build sequence

The agent orchestrates these. Each query and chart step hands off to a focused skill.

1. DESIGN IT FIRST. Read reference/design.md: who opens it, the decision it serves, the archetype, the form each tile takes, and the depth plan. Skipping this is what produces an app that enumerates the model - a KPI row and a chart grid, whatever the domain - instead of one that answers a question. Hand the brief to the user before scaffolding.
2. READ THE MODEL. Get the model's real source and view names, through your environment's context tool if it has one, or by opening the .malloy file directly. Never guess field or view names.
3. SCAFFOLD the package (template below).
4. WRITE THE QUERIES. Read reference/runtime.md. Validate each before pasting it into the page, using whatever query tool your environment provides or a running Publisher (see reference/runtime.md). Malloy syntax questions go to skill:malloy-queries.
5. CHOOSE CHARTS with skill:malloy-charts when rendering through <malloy-render>; otherwise it is your own chart library drawing the returned rows. Vendor any chart library into public/ and load it locally, not from a CDN. Two reasons: embedded author JavaScript runs with the viewing user's data authority, and a blocked CDN (agent sandboxes and many corporate networks block them) is easy to miss, because the script never runs and the charts come up empty. The storefront example ships its chart library in public/vendor/ and loads it from public/index.html as ./vendor/chart.umd.js. Copy its vendoring, not its loading (it uses a plain <script>, which the next sentences rule out), and resolve the path against the page's own directory: a page in a subdirectory (public/reports/index.html) needs ../vendor/chart.umd.js. A wrong relative path 404s and leaves the charts blank, which is the failure you are trying to avoid. Load it off the critical path (<link rel="preload">, then injected on the first chart), not as a plain <script> ahead of the app: it is usually most of the page's weight and would hold every query until it has parsed (reference/performance.md).
6. EMBED (optional). Read reference/embedding.md.
7. PREVIEW with the local authoring loop (below).
8. VERIFY before you call it done (see "What 'done' means" below). This step is not optional.