@holistics/anfra-sdk 0.7.1 → 0.8.0

package/README.md

@@ -44,6 +44,29 @@ app.subscribe(() => render(byRegion.result));
 await app.execute();
 ```
 
+A reader can download a query's whole result, with the inputs its result on screen was run with:
+
+```js
+if (Anfra.features.export && Anfra.user.permissions.canExportData) {
+  button.onclick = () => byRegion.export().catch((err) => showError(err.message));
+}
+```
+
+`export()` resolves once the file is made and the host has started saving it, with its link and
+`rowCount`. The file is a CSV named after the app and the query unless you pass `filename`.
+
+A reader can download a picture of the app, or of one block or container, as they see it:
+
+```js
+await Anfra.render({ block: 'trend', format: 'png' });   // or 'pdf'; no node: the whole app
+```
+
+It works only where the host turned rendering on (`mountDataApp({ render: true })`; `anfra serve`
+does). Check `Anfra.features.render` and `Anfra.user.permissions.canExportData` before offering it, and
+mark what shouldn't be drawn (the download button itself) `data-anfra-render="skip"`. Serve images
+and web fonts with CORS: an image without it is left blank (listed in the result's `omitted`), a
+font without it falls back.
+
 `Anfra.datasets` describes what there is to query. For TypeScript, `@holistics/anfra-sdk/ambient` declares the
 global.
 
@@ -81,20 +104,22 @@ const mounted = mountDataApp({
   baseHref: '/appserve/files/sales/',                    // where its relative URLs resolve
   datasets,
   user,
-  backend: coreApiBackend(client, { datasets }),         // queries and field suggestions, as core.query
+  backend: coreApiBackend(client, { datasets }),         // queries, field suggestions and exports, as core ops
+  render: true,                                          // let it save PNGs and PDFs of itself (off by default)
 });
-// mounted.setInspecting(true) to receive inspection snapshots; mounted.unmount() when done.
+// mounted.setInspecting(true) to receive inspection snapshots; mounted.render({ format: 'pdf' }) to
+// save a picture of the app (needs render: true); mounted.unmount() when done.
 ```
 
 `mountDataApp` puts the definition in an iframe with `sandbox="allow-scripts"`, as its `srcdoc`,
-with the frame bootstrap and the provisioned data ahead of it. The bootstrap's Backend forwards each call to the host over postMessage; the host answers it with the Backend it was given.
+with the frame bootstrap and the provisioned data ahead of it. The bootstrap's Backend forwards each call to the host over postMessage; the host answers it with the Backend it was given. An export's file is saved from the host's page, by following its link: the frame can't download. A Backend without `exportQuery` makes a host that can't export, and its frames see `Anfra.features.export` false.
 
 ## The boundary
 
 A Data App definition can come from any author, often an agent, which may not think of security while building an analysis. So the SDK guards it for its author, and makes the safe way the easy one:
 
 - Its frame has an opaque origin. Its own requests to the API are cross-origin, which `anfra serve` refuses, and carry no credentials on a platform that has them.
-- The bridge answers only the Backend's two methods, `submitQuery` and `fieldSuggestions`. Nothing else of the API is reachable from a frame.
+- The bridge answers only the Backend's methods, `submitQuery`, `fieldSuggestions` and `exportQuery`, and the two a rendering needs, the renderer's code and saving its file. Nothing else of the API is reachable from a frame.
 - `@holistics/anfra-sdk/app` imports only `common`: the script injected into a frame carries no API client.  A test on the built frame script holds this.
 
 ## Development

package/dist/api.d.ts

@@ -1,5 +1,5 @@
 import { Client } from 'openapi-fetch';
-import { D as DatasetDescriptor, B as Backend, g as BackendQueryRequest } from './types-BlzJVcUl.js';
+import { D as DatasetDescriptor, B as Backend, f as BackendExportRequest, h as BackendQueryRequest } from './types-IR4TNw-M.js';
 import { D as DataAppError } from './errors-CKvqVaqU.js';
 
 /**
@@ -1348,6 +1348,7 @@ type CoreClient = Client<paths>;
 declare function coreClient(baseUrl: string, fetchImpl?: typeof fetch): CoreClient;
 
 type QueryRunInput = components['schemas']['QueryRunInput'];
+type ExportInput = components['schemas']['ExportInput'];
 /** How many values a filter control is offered at most. */
 declare const SUGGESTION_LIMIT = 100;
 interface CoreApiBackendOptions {
@@ -1359,9 +1360,11 @@ interface CoreApiBackendOptions {
 }
 /** The core.query input a Backend request is: the AQL, its Query Input, its paging and timezone. */
 declare function toQueryInput(request: BackendQueryRequest): QueryRunInput;
+/** The core.query.export input an export request is: the query as a run sends it, and the file. */
+declare function toExportInput(request: BackendExportRequest): ExportInput;
 /**
- * A Backend over the core API: a Data App's queries as `core.query`, and its field suggestions as
- * one `core.query` too. The same on every host: `/api` on `anfra serve`, `/api/o/{org}` on
+ * A Backend over the core API: a Data App's queries as `core.query`, its field suggestions as one
+ * `core.query` too, and its exports as `core.query.export`. The same on every host: `/api` on `anfra serve`, `/api/o/{org}` on
  * anfra-cloud. A host's page uses it; a Data App's frame never does.
  */
 declare function coreApiBackend(base: string | CoreClient, options?: CoreApiBackendOptions): Backend;
@@ -1404,4 +1407,4 @@ interface ApiErrorBody {
  */
 declare function toSdkError(status: number, body: ApiErrorBody | undefined): DataAppError;
 
-export { type ApiErrorBody, type CoreApiBackendOptions, type CoreClient, type LoadedDatasets, SUGGESTION_LIMIT, type components, coreApiBackend, coreClient, loadDatasets, type paths, toDescriptor, toQueryInput, toSdkError };
+export { type ApiErrorBody, type CoreApiBackendOptions, type CoreClient, type LoadedDatasets, SUGGESTION_LIMIT, type components, coreApiBackend, coreClient, loadDatasets, type paths, toDescriptor, toExportInput, toQueryInput, toSdkError };

package/dist/api.js

@@ -2,8 +2,7 @@ import {
   PermissionError,
   QueryError,
   TransportError
-} from "./chunk-KCTLO3CO.js";
-import "./chunk-PKBMQBKP.js";
+} from "./chunk-KBXITYQK.js";
 
 // src/api/client.ts
 import createClient from "openapi-fetch";
@@ -59,6 +58,18 @@ function toQueryInput(request) {
     ...request.timezone ? { timezone: request.timezone } : {}
   };
 }
+function toExportInput(request) {
+  return {
+    query: request.aql,
+    dataset: request.dataset,
+    input: request.input,
+    ...request.timezone ? { timezone: request.timezone } : {},
+    // The server names its formats; one it does not know it refuses, with a message the author sees.
+    ...request.format ? { format: request.format } : {},
+    ...request.formatOptions ? { format_options: request.formatOptions } : {},
+    ...request.filename ? { filename: request.filename } : {}
+  };
+}
 function toColumns(columns) {
   return columns.map((column) => {
     const { semantic_type: semanticType, arrow_type: arrowType, db_type: dbType } = column;
@@ -70,10 +81,10 @@ function toColumns(columns) {
     return { ...column, semantic_type: semanticType, arrow_type: arrowType, db_type: dbType };
   });
 }
-async function runQuery(client, body, signal) {
+async function answer(call) {
   let result;
   try {
-    result = await client.POST("/core.query", { body, signal });
+    result = await call();
   } catch (err) {
     if (isAbort(err)) throw err;
     throw new TransportError(`The server could not be reached: ${err.message}`);
@@ -82,6 +93,9 @@ async function runQuery(client, body, signal) {
   if (!data) throw toSdkError(response.status, error?.error);
   return data;
 }
+function runQuery(client, body, signal) {
+  return answer(() => client.POST("/core.query", { body, signal }));
+}
 function coreApiBackend(base, options = {}) {
   const client = typeof base === "string" ? coreClient(base) : base;
   return {
@@ -127,6 +141,17 @@ function coreApiBackend(base, options = {}) {
         page_size: SUGGESTION_LIMIT
       }, signal);
       return data.result.records.map((row) => row[0]).filter((v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean");
+    },
+    /** An export as `core.query.export`: the server runs the query to completion, then answers its link. */
+    async exportQuery(request, signal) {
+      const link = await answer(() => client.POST("/core.query.export", { body: toExportInput(request), signal }));
+      return {
+        url: link.url,
+        filename: link.filename,
+        format: link.format,
+        rowCount: link.row_count,
+        expiresAt: new Date(link.expires_at)
+      };
     }
   };
 }
@@ -172,6 +197,7 @@ export {
   coreClient,
   loadDatasets,
   toDescriptor,
+  toExportInput,
   toQueryInput,
   toSdkError
 };

package/dist/app.d.ts

@@ -1,8 +1,8 @@
-import { L as Listener, a1 as Unsubscribe, D as DatasetDescriptor, E as EntityKind, j as Condition, w as FilterDeclaration, x as FilterValueType, B as Backend, k as ConditionValue, n as DateDrillDeclaration, o as DateGrain, v as FilterAggregation, l as ControlMappingJson, m as CrossFilterJson, X as SdkFeatures, Y as Selection, Z as SelectionCondition, V as Row, K as LocateKind, P as QueryDeclaration, U as QueryState, S as QueryResult, T as QuerySort, a as AppDeclaration, s as ExecuteOptions, t as ExecuteSummary, b as AppJson, I as InspectedApp, a2 as User, W as SdkEnvironment, J as InspectedStructure } from './types-BlzJVcUl.js';
-export { A as Aggregation, c as ArrowType, d as BackendCondition, e as BackendDateDrill, f as BackendFilter, g as BackendQueryRequest, h as BackendQueryResult, i as BackendSort, C as ColumnMeta, p as DateTransformation, q as EntityRef, r as EntityUsage, F as FILTER_AGGREGATIONS, u as FieldSuggestionsRequest, y as InspectedControl, z as InspectedError, G as InspectedQuery, H as InspectedSelection, M as LocateTarget, N as MappingJson, O as Operator, Q as QueryDebug, R as QueryInput, _ as SemanticType, $ as StructureKind, a0 as StructureNode } from './types-BlzJVcUl.js';
+import { P as Listener, a9 as Unsubscribe, D as DatasetDescriptor, E as EntityKind, k as Condition, H as FilterDeclaration, I as FilterValueType, B as Backend, l as ConditionValue, o as DateDrillDeclaration, p as DateGrain, G as FilterAggregation, m as ControlMappingJson, n as CrossFilterJson, a3 as SdkFeatures, a4 as Selection, a5 as SelectionCondition, a1 as Row, x as ExportOptions, y as ExportResult, Q as LocateKind, V as QueryDeclaration, Z as QueryState, X as QueryResult, Y as QuerySort, a as AppDeclaration, t as ExecuteOptions, u as ExecuteSummary, b as AppJson, J as InspectedApp, aa as User, a2 as SdkEnvironment, $ as RenderRequest, a0 as Rendering, O as InspectedStructure } from './types-IR4TNw-M.js';
+export { A as Aggregation, c as ArrowType, d as BackendCondition, e as BackendDateDrill, f as BackendExportRequest, g as BackendFilter, h as BackendQueryRequest, i as BackendQueryResult, j as BackendSort, C as ColumnMeta, q as DateTransformation, r as EntityRef, s as EntityUsage, v as ExportFormat, w as ExportFormatOptions, F as FILTER_AGGREGATIONS, z as FieldSuggestionsRequest, K as InspectedControl, L as InspectedError, M as InspectedQuery, N as InspectedSelection, R as LocateTarget, S as MappingJson, T as Operator, U as QueryDebug, W as QueryInput, _ as RenderFormat, a6 as SemanticType, a7 as StructureKind, a8 as StructureNode } from './types-IR4TNw-M.js';
 import { D as DataAppError } from './errors-CKvqVaqU.js';
 export { P as PermissionError, Q as QueryError, T as TransportError, V as ValidationError } from './errors-CKvqVaqU.js';
-export { B as BridgeError, a as BridgeMethod, F as FrameMessage, H as HostMessage, P as PROVISION_ELEMENT_ID, b as Provision } from './bridge-BKx7u5mX.js';
+export { B as BridgeError, a as BridgeMethod, F as FrameMessage, H as HostMessage, P as PROVISION_ELEMENT_ID, b as Provision } from './bridge-BmbS9J4V.js';
 
 interface NotificationTarget {
     notifyChange(): void;
@@ -190,6 +190,8 @@ interface AppContext {
     select(query: Query, rows: readonly Row[], fields?: readonly string[]): void;
     /** Runs one more page for a query that already has a result. */
     fetchPage(query: Query): Promise<void>;
+    /** Exports a query's whole result, with what it was last run with. */
+    exportQuery(query: Query, options?: ExportOptions): Promise<ExportResult>;
     /** Brings an entity's marked elements into view; false when none is on the page. */
     locate(kind: LocateKind, name: string): boolean;
 }
@@ -254,6 +256,17 @@ declare class Query extends Observable {
     abort(): void;
     /** Fetches the next page and appends it. Rejects rather than swallowing, unlike `execute()`. */
     fetchMore(): Promise<void>;
+    /**
+     * Exports this query's whole result as a file, and has the host save it for the reader.
+     *
+     * Every row, not only the pages loaded, with what the result on screen was last run with: the
+     * mapped controls, the selection, the sort, the timezone. A control the reader changed but has
+     * not applied is not in it. Resolves once the file is made and its download has started, with
+     * its link and row count; rejects with a `DataAppError` naming this query, and changes nothing on
+     * the query either way. Show the button when `Anfra.features.export` and
+     * `Anfra.user.permissions.canExportData` are both true.
+     */
+    export(options?: ExportOptions): Promise<ExportResult>;
     /**
      * Cross-filters this query's targets by the rows the reader picked.
      *
@@ -389,6 +402,11 @@ declare class App extends Observable implements AppContext {
     abort(): void;
     /** @internal Backs `query.fetchMore()`. Rejects, so an explicit page request reports its failure. */
     fetchPage(query: Query): Promise<void>;
+    /**
+     * @internal Backs `query.export()`. Built from the applied state, as `fetchPage` is, so the file
+     * holds what the reader is looking at, every row of it. Touches nothing on the query.
+     */
+    exportQuery(query: Query, options?: ExportOptions): Promise<ExportResult>;
     /**
      * The declaration and nothing else — no datasets, no backend, no reader state. This is the
      * shape a persisted Data App record will take, which is why mapping edges are already generic.
@@ -451,9 +469,22 @@ declare class Sdk {
     readonly user: Readonly<User>;
     private readonly indices;
     private readonly backend;
-    private readonly features;
+    /**
+     * What the host can do beyond queries. `export` says whether `query.export()` can work here, and
+     * `render` whether `render()` can: show either's button only when it and
+     * `user.permissions.canExportData` are both true.
+     */
+    readonly features: Readonly<SdkFeatures>;
+    private readonly renderHook?;
     constructor(environment: SdkEnvironment);
     createApp(declaration?: AppDeclaration): App;
+    /**
+     * Render the whole app, or one block or container of its structure by id, as a PNG or a PDF, and
+     * have the host save it for the reader. What is drawn is what the page shows now: `await
+     * app.execute()` first for fresh results. Elements marked `data-anfra-render="skip"` are left out.
+     * Rejects with a `ValidationError` naming what to fix.
+     */
+    render(request: RenderRequest): Promise<Rendering>;
     /**
      * Every app this instance has built, for a host rendering an inspection panel.
      *
@@ -524,4 +555,4 @@ declare function buildStructure(doc: Document, apps: readonly App[]): BuiltStruc
 /** Provision the SDK in `win` from its host, and install it. Returns once `Anfra` exists. */
 declare function bootstrap(win: Window): void;
 
-export { App, AppDeclaration, AppJson, Backend, Condition, ConditionValue, Control, ControlMappingJson, CrossFilter, CrossFilterJson, DataAppError, DatasetDescriptor, DateDrillControl, DateDrillDeclaration, DateGrain, type Edge, EntityKind, ExecuteOptions, ExecuteSummary, Filter, FilterAggregation, FilterDeclaration, FilterValueType, InspectedApp, InspectedStructure, Listener, LocateKind, Mapping, OVERLAY_ID, Query, QueryDeclaration, QueryResult, QuerySort, QueryState, Row, SANDBOX_GLOBAL, ATTR as STRUCTURE_ATTRIBUTES, Sdk, SdkEnvironment, SdkFeatures, Selection, SelectionCondition, Unsubscribe, User, VERSION, bootstrap, buildStructure, createSdk, installSandbox, parseRef };
+export { App, AppDeclaration, AppJson, Backend, Condition, ConditionValue, Control, ControlMappingJson, CrossFilter, CrossFilterJson, DataAppError, DatasetDescriptor, DateDrillControl, DateDrillDeclaration, DateGrain, type Edge, EntityKind, ExecuteOptions, ExecuteSummary, ExportOptions, ExportResult, Filter, FilterAggregation, FilterDeclaration, FilterValueType, InspectedApp, InspectedStructure, Listener, LocateKind, Mapping, OVERLAY_ID, Query, QueryDeclaration, QueryResult, QuerySort, QueryState, RenderRequest, Rendering, Row, SANDBOX_GLOBAL, ATTR as STRUCTURE_ATTRIBUTES, Sdk, SdkEnvironment, SdkFeatures, Selection, SelectionCondition, Unsubscribe, User, VERSION, bootstrap, buildStructure, createSdk, installSandbox, parseRef };

package/dist/app.js

@@ -9,11 +9,9 @@ import {
   PermissionError,
   QueryError,
   TransportError,
-  ValidationError
-} from "./chunk-KCTLO3CO.js";
-import {
+  ValidationError,
   __publicField
-} from "./chunk-PKBMQBKP.js";
+} from "./chunk-KBXITYQK.js";
 
 // src/app/observable.ts
 var Observable = class {
@@ -169,6 +167,19 @@ var Query = class extends Observable {
     this._page += 1;
     await this.app.fetchPage(this);
   }
+  /**
+   * Exports this query's whole result as a file, and has the host save it for the reader.
+   *
+   * Every row, not only the pages loaded, with what the result on screen was last run with: the
+   * mapped controls, the selection, the sort, the timezone. A control the reader changed but has
+   * not applied is not in it. Resolves once the file is made and its download has started, with
+   * its link and row count; rejects with a `DataAppError` naming this query, and changes nothing on
+   * the query either way. Show the button when `Anfra.features.export` and
+   * `Anfra.user.permissions.canExportData` are both true.
+   */
+  export(options = {}) {
+    return this.app.exportQuery(this, options);
+  }
   /**
    * Cross-filters this query's targets by the rows the reader picked.
    *
@@ -624,7 +635,7 @@ function toResult(query, data) {
     ...data.debug ? { debug: data.debug } : {}
   };
 }
-function buildRequest(query, mappings, selection, context) {
+function buildQuery(query, mappings, selection, context) {
   const mappedFilters = mappings.map((mapping) => toFilter(mapping, mapping.from.appliedCondition)).filter((filter) => filter !== void 0);
   const dateDrills = mappings.map((mapping) => toDateDrill(mapping, mapping.from.appliedCondition)).filter((drill) => drill !== void 0);
   const selectionFilters = selection.conditions.map((condition) => ({
@@ -642,14 +653,33 @@ function buildRequest(query, mappings, selection, context) {
       sorts: query.sort.map((sort) => ({ field: sort.field, direction: sort.direction ?? "asc" })),
       dateDrills
     },
-    // Omitted for a query that declares no page size, so the backend returns every row.
-    ...query.pageSize !== void 0 ? { page: query.page, pageSize: query.pageSize } : {},
     // Omitted entirely when the app declares none, so the backend applies its own default rather
     // than the SDK guessing the browser's.
-    ...context.timezone ? { timezone: context.timezone } : {},
+    ...context.timezone ? { timezone: context.timezone } : {}
+  };
+}
+function buildRequest(query, mappings, selection, context) {
+  return {
+    ...buildQuery(query, mappings, selection, context),
+    // Omitted for a query that declares no page size, so the backend returns every row.
+    ...query.pageSize !== void 0 ? { page: query.page, pageSize: query.pageSize } : {},
     ...context.bustCache ? { bustCache: true } : {}
   };
 }
+function defaultExportFilename(query, title) {
+  const safeTitle = title?.replace(/[/\\]/g, "-").replace(/\p{Cc}/gu, "").trim();
+  return safeTitle ? `${safeTitle} - ${query.name}` : query.name;
+}
+function buildExportRequest(query, mappings, selection, context, options) {
+  const format2 = options.format ?? "csv";
+  const formatOptions = format2 === "csv" ? { bom: true, ...options.formatOptions } : options.formatOptions;
+  return {
+    ...buildQuery(query, mappings, selection, context),
+    format: format2,
+    ...formatOptions ? { formatOptions } : {},
+    filename: options.filename?.trim() || defaultExportFilename(query, context.title)
+  };
+}
 async function runQuery(query, mappings, selection, context, signal) {
   const request = buildRequest(query, mappings, selection, context);
   const data = await context.backend.submitQuery(request, signal);
@@ -1204,6 +1234,14 @@ function toDataAppError(err, entity) {
   if (err instanceof DataAppError) return err;
   return new QueryError(err?.message ?? "The query failed.", entity, err);
 }
+function toExportError(err, entity) {
+  if (err instanceof DataAppError && err.entity) return err;
+  const message = err?.message || "The export failed.";
+  if (err instanceof PermissionError) return new PermissionError(message, entity);
+  if (err instanceof TransportError) return new TransportError(message, err.status, entity);
+  if (err instanceof ValidationError) return new ValidationError(message, entity);
+  return new QueryError(message, entity, err);
+}
 var App = class extends Observable {
   constructor(declaration, datasets, backend, features) {
     super();
@@ -1547,6 +1585,32 @@ var App = class extends Observable {
       if (query.controller === controller) query.controller = void 0;
     }
   }
+  /**
+   * @internal Backs `query.export()`. Built from the applied state, as `fetchPage` is, so the file
+   * holds what the reader is looking at, every row of it. Touches nothing on the query.
+   */
+  async exportQuery(query, options = {}) {
+    const { backend } = this;
+    if (this.features?.export === false || !backend.exportQuery) {
+      throw new TransportError("This host cannot make exports.", void 0, query.name);
+    }
+    const request = buildExportRequest(
+      query,
+      this.mappingsTo(query.name),
+      {
+        conditions: this.selectionConditionsFor(query.name, "applied"),
+        expression: this.selectionExpressionFor(query.name, "applied")
+      },
+      { backend, timezone: this._timezone, title: this.title },
+      options
+    );
+    try {
+      return await backend.exportQuery(request, options.signal ?? new AbortController().signal);
+    } catch (err) {
+      if (isAbort(err)) throw err;
+      throw toExportError(err, query.name);
+    }
+  }
   /* ----------------------------------------------------------------
   Serialisation
   ---------------------------------------------------------------- */
@@ -1661,7 +1725,7 @@ var App = class extends Observable {
 };
 
 // package.json
-var version = "0.7.1";
+var version = "0.8.0";
 
 // src/app/sdk.ts
 var VERSION = version;
@@ -1683,7 +1747,13 @@ var Sdk = class {
     __publicField(this, "user");
     __publicField(this, "indices");
     __publicField(this, "backend");
+    /**
+     * What the host can do beyond queries. `export` says whether `query.export()` can work here, and
+     * `render` whether `render()` can: show either's button only when it and
+     * `user.permissions.canExportData` are both true.
+     */
     __publicField(this, "features");
+    __publicField(this, "renderHook");
     if (!environment?.datasets) {
       throw new ValidationError(
         "No datasets provided. The host must call createSdk({ datasets }) before an app can be declared."
@@ -1711,7 +1781,14 @@ var Sdk = class {
       ])
     );
     this.backend = environment.backend;
-    this.features = Object.freeze({ ...environment.features });
+    this.renderHook = environment.render;
+    this.features = Object.freeze({
+      ...environment.features,
+      // Known from the Backend itself when the host does not say. In a frame the bridge's Backend
+      // has every method, so there it is the host's provision that says.
+      export: environment.features?.export ?? typeof environment.backend.exportQuery === "function",
+      render: environment.features?.render ?? typeof environment.render === "function"
+    });
   }
   createApp(declaration = {}) {
     const app = new App(declaration, this.indices, this.backend, this.features);
@@ -1719,6 +1796,18 @@ var Sdk = class {
     this._apps.push(app);
     return app;
   }
+  /**
+   * Render the whole app, or one block or container of its structure by id, as a PNG or a PDF, and
+   * have the host save it for the reader. What is drawn is what the page shows now: `await
+   * app.execute()` first for fresh results. Elements marked `data-anfra-render="skip"` are left out.
+   * Rejects with a `ValidationError` naming what to fix.
+   */
+  render(request) {
+    if (!this.renderHook || this.features.render === false) {
+      return Promise.reject(new ValidationError("This host does not render Data Apps: check Anfra.features.render first."));
+    }
+    return this.renderHook(request);
+  }
   /**
    * Every app this instance has built, for a host rendering an inspection panel.
    *
@@ -1780,6 +1869,92 @@ function startPick(doc, handlers) {
   };
 }
 
+// src/render/types.ts
+var RENDERER_GLOBAL = "__anfraRenderer";
+
+// src/app/render.ts
+var SKIP_ATTRIBUTE = "data-anfra-render";
+var EXTENSIONS = { png: "png", pdf: "pdf" };
+var SETTLE_MS = 1e4;
+function filenameFor(request, doc, apps, element) {
+  const ext = EXTENSIONS[request.format];
+  let name = request.filename?.trim();
+  if (!name) {
+    const title = apps.find((app) => app.title)?.title || doc.title.trim() || "Data App";
+    const node = element && (element.getAttribute(ATTR.label) || request.block || request.container);
+    name = node ? `${title} - ${node}` : title;
+  }
+  name = name.replace(/[/\\]/g, "-").replace(/\p{Cc}/gu, "").trim() || "Data App";
+  return name.toLowerCase().endsWith(`.${ext}`) ? name : `${name}.${ext}`;
+}
+function targetOf(request, doc) {
+  if (request.block !== void 0 && request.container !== void 0) {
+    throw new ValidationError("Render a block or a container, not both.", request.block);
+  }
+  if (request.format !== "png" && request.format !== "pdf") {
+    throw new ValidationError(`Can't render as '${String(request.format)}': the formats are 'png' and 'pdf'.`);
+  }
+  const { pixelRatio } = request;
+  if (pixelRatio !== void 0 && !(Number.isFinite(pixelRatio) && pixelRatio > 0)) {
+    throw new ValidationError(`pixelRatio ${String(pixelRatio)} is not a positive number.`);
+  }
+  const kind = request.block !== void 0 ? "block" : request.container !== void 0 ? "container" : void 0;
+  if (!kind) return { element: null };
+  const id = request.block ?? request.container;
+  const element = [...doc.querySelectorAll(`[${ATTR[kind]}]`)].find((el) => el.getAttribute(ATTR[kind]) === id);
+  if (!element) throw new ValidationError(`No element is marked ${ATTR[kind]}="${id}" on the page.`, id);
+  return { element, entity: id };
+}
+function skip(element) {
+  return element.id === OVERLAY_ID || element.getAttribute(SKIP_ATTRIBUTE) === "skip";
+}
+function createRender(win, deps) {
+  let loading;
+  const load = () => {
+    const ready = win[RENDERER_GLOBAL];
+    if (ready) return Promise.resolve(ready);
+    loading ?? (loading = deps.ask.renderer().then((code) => {
+      const script = win.document.createElement("script");
+      script.textContent = code;
+      (win.document.head ?? win.document.documentElement).appendChild(script);
+      script.remove();
+      const installed = win[RENDERER_GLOBAL];
+      if (!installed) throw new ValidationError("The host sent a renderer that did not install.");
+      return installed;
+    }).catch((err) => {
+      loading = void 0;
+      throw err;
+    }));
+    return loading;
+  };
+  return async (request) => {
+    const doc = win.document;
+    const { element, entity } = targetOf(request ?? {}, doc);
+    const filename = filenameFor(request, doc, deps.apps(), element);
+    try {
+      const renderer = await load();
+      const drawing = await renderer.draw(element, { format: request.format, pixelRatio: request.pixelRatio, skip });
+      await deps.ask.saveFile({ blob: drawing.blob, filename });
+      return { filename, format: request.format, ...drawing };
+    } catch (err) {
+      if (err instanceof ValidationError && err.entity) throw err;
+      throw new ValidationError(err?.message || "The rendering failed.", entity);
+    }
+  };
+}
+async function settle(win, apps, timeout = SETTLE_MS) {
+  const busy = () => apps().some((app) => Object.values(app.queries).some((query) => query.state === "executing"));
+  const deadline = Date.now() + timeout;
+  while (busy() && Date.now() < deadline) {
+    await new Promise((resolve) => {
+      win.setTimeout(resolve, 100);
+    });
+  }
+  await new Promise((resolve) => {
+    win.requestAnimationFrame(() => resolve(void 0));
+  });
+}
+
 // src/app/bootstrap.ts
 function abortError() {
   const err = new Error("Aborted");
@@ -1792,6 +1967,8 @@ function toError(error) {
       return new PermissionError(error.message);
     case "TransportError":
       return new TransportError(error.message);
+    case "ValidationError":
+      return new ValidationError(error.message);
     default:
       return new QueryError(error?.message || "The query failed.");
   }
@@ -1829,6 +2006,14 @@ function bootstrap(win) {
       case "anfra:pick-watch":
         setPicking(message.on);
         return;
+      case "anfra:render": {
+        const { id } = message;
+        settle(win, () => instance.apps).then(() => instance.render(message.request)).then(
+          (result) => post({ type: "anfra:rendered", id, ok: true, result }),
+          (err) => post({ type: "anfra:rendered", id, ok: false, error: { name: err?.name ?? "ValidationError", message: err?.message ?? "The rendering failed." } })
+        );
+        return;
+      }
       default:
     }
   });
@@ -1853,9 +2038,28 @@ function bootstrap(win) {
       if (result.debug?.executedAt) result.debug.executedAt = new Date(result.debug.executedAt);
       return result;
     }),
-    fieldSuggestions: (request, signal) => call("fieldSuggestions", request, signal)
+    fieldSuggestions: (request, signal) => call("fieldSuggestions", request, signal),
+    exportQuery: (request, signal) => call("exportQuery", request, signal).then((result) => {
+      result.expiresAt = new Date(result.expiresAt);
+      return result;
+    })
   };
-  const instance = createSdk({ datasets: provision.datasets, user: provision.user, backend });
+  const render = createRender(win, {
+    ask: {
+      renderer: () => call("renderer", null, new AbortController().signal),
+      saveFile: (request) => call("saveFile", request, new AbortController().signal)
+    },
+    apps: () => instance.apps
+  });
+  const instance = createSdk({
+    datasets: provision.datasets,
+    user: provision.user,
+    backend,
+    render,
+    // A host older than `features` provisions none: say it can neither export nor render, rather
+    // than let the bridge's Backend, which has every method, claim an export.
+    features: { export: false, render: false, ...provision.features }
+  });
   const doc = win.document;
   let structure;
   let lastStructureJson = "";

package/dist/{bridge-BKx7u5mX.d.ts → bridge-BmbS9J4V.d.ts}

@@ -1,4 +1,4 @@
-import { g as BackendQueryRequest, u as FieldSuggestionsRequest, I as InspectedApp, J as InspectedStructure, M as LocateTarget, D as DatasetDescriptor, a2 as User } from './types-BlzJVcUl.js';
+import { h as BackendQueryRequest, z as FieldSuggestionsRequest, f as BackendExportRequest, a0 as Rendering, J as InspectedApp, O as InspectedStructure, R as LocateTarget, $ as RenderRequest, D as DatasetDescriptor, aa as User, a3 as SdkFeatures } from './types-IR4TNw-M.js';
 
 /**
  * The bridge: the postMessage protocol between a Data App's frame (`app`'s bootstrap) and the
@@ -6,12 +6,22 @@ import { g as BackendQueryRequest, u as FieldSuggestionsRequest, I as InspectedA
  * makes to its Backend crosses here, and the host answers it.
  */
 
-/** The Backend methods a frame may call: the bridge serves these and nothing else. */
-type BridgeMethod = 'submitQuery' | 'fieldSuggestions';
+/**
+ * What a frame may ask its host: the Backend's methods, and the two a rendering needs (the
+ * renderer's code, and saving a file). The bridge serves these and nothing else.
+ */
+type BridgeMethod = 'submitQuery' | 'fieldSuggestions' | 'exportQuery' | 'renderer' | 'saveFile';
+/** A file the frame made, for the host to save for the reader: the frame cannot download. */
+interface SaveFileRequest {
+    blob: Blob;
+    filename: string;
+}
 /** What the host provisions a frame with, as JSON in `<script type="application/json" id="anfra-provision">`. */
 interface Provision {
     datasets: Record<string, DatasetDescriptor>;
     user: User;
+    /** What the host can do beyond queries: exports, rendering. Absent from a host older than this field. */
+    features?: SdkFeatures;
     /** The host page's origin: where the frame posts, so nothing else can read its messages. */
     hostOrigin: string;
 }
@@ -29,6 +39,37 @@ type FrameMessage = {
     id: number;
     method: 'fieldSuggestions';
     request: FieldSuggestionsRequest;
+}
+/** The host makes the file, starts saving it for the reader, then answers its link. */
+ | {
+    type: 'anfra:request';
+    id: number;
+    method: 'exportQuery';
+    request: BackendExportRequest;
+}
+/** The renderer's code, asked for on the frame's first rendering; answered as a string. */
+ | {
+    type: 'anfra:request';
+    id: number;
+    method: 'renderer';
+    request: null;
+} | {
+    type: 'anfra:request';
+    id: number;
+    method: 'saveFile';
+    request: SaveFileRequest;
+}
+/** The answer to the host's `anfra:render`, by its id. */
+ | {
+    type: 'anfra:rendered';
+    id: number;
+    ok: true;
+    result: Rendering;
+} | {
+    type: 'anfra:rendered';
+    id: number;
+    ok: false;
+    error: BridgeError;
 } | {
     type: 'anfra:cancel';
     id: number;
@@ -76,6 +117,12 @@ type HostMessage = {
  | {
     type: 'anfra:pick-watch';
     on: boolean;
+}
+/** Render the app or one node, once its queries settle, and save it; the frame answers `anfra:rendered`. */
+ | {
+    type: 'anfra:render';
+    id: number;
+    request: RenderRequest;
 };
 
 export { type BridgeError as B, type FrameMessage as F, type HostMessage as H, PROVISION_ELEMENT_ID as P, type BridgeMethod as a, type Provision as b };