@altertable/data-app 0.63.0 → 0.65.0

package/dist/worker.js

@@ -48,19 +48,273 @@ function trustedParent(config, searchParams) {
 var TOKEN_RE = /^(?=.{1,63}$)[a-z0-9]+(?:-[a-z0-9]+)+-app-[1-9][0-9]*$/;
 var PAGE_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; connect-src 'none'; form-action 'none'; base-uri 'none'";
 var inlineBootstrap = `(() => {
+  // src/core/logger.ts
+  function isLogEntry(value) {
+    if (!value || typeof value !== "object")
+      return false;
+    const entry = value;
+    return (entry.method === "log" || entry.method === "info" || entry.method === "warn" || entry.method === "error") && Array.isArray(entry.args) && entry.args.length <= 128;
+  }
+
   // src/core/bridge.ts
   var BRIDGE = "altertable:data-app";
   var MAX_PENDING = 128;
   var REQUEST_TIMEOUT_MS = 60000;
-  function isBridgeMessage(value) {
-    if (!value || typeof value !== "object")
-      return false;
-    const message = value;
-    return message.channel === BRIDGE && message.version === 1 && typeof message.type === "string" && typeof message.documentId === "string" && message.documentId.length > 0 && message.documentId.length <= 128;
-  }
   function validId(value) {
     return typeof value === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(value);
   }
+  function event({
+    wire,
+    from,
+    session,
+    parse
+  }) {
+    return { wire, from, session, parse };
+  }
+  function id(fields) {
+    if (!validId(fields.id))
+      throw new Error("Invalid request ID.");
+    return fields.id;
+  }
+  function string(fields, key) {
+    const value = fields[key];
+    if (typeof value !== "string")
+      throw new Error(\`Invalid \${key}.\`);
+    return value;
+  }
+  function empty() {
+    return {};
+  }
+  var bridgeProtocol = {
+    channel: BRIDGE,
+    version: 1,
+    events: {
+      connect: event({
+        wire: "bridge:connect",
+        from: "host",
+        session: "none",
+        parse: empty
+      }),
+      ready: event({
+        wire: "bridge:ready",
+        from: "app",
+        session: "none",
+        parse: empty
+      }),
+      initialize: event({
+        wire: "bridge:initialize",
+        from: "host",
+        session: "establish",
+        parse: (fields) => ({ state: fields.state })
+      }),
+      request: event({
+        wire: "bridge:request",
+        from: "app",
+        session: "current",
+        parse: (fields) => {
+          const route = string(fields, "route");
+          if (!route || route.length > 256)
+            throw new Error("Invalid message route.");
+          return { id: id(fields), route, payload: fields.payload };
+        }
+      }),
+      result: event({
+        wire: "bridge:result",
+        from: "host",
+        session: "current",
+        parse: (fields) => {
+          if (!Object.hasOwn(fields, "response"))
+            throw new Error("Missing response.");
+          return { id: id(fields), response: fields.response };
+        }
+      }),
+      error: event({
+        wire: "bridge:error",
+        from: "host",
+        session: "current",
+        parse: (fields) => {
+          if (fields.requestId !== undefined && typeof fields.requestId !== "string")
+            throw new Error("Invalid requestId.");
+          return {
+            id: id(fields),
+            code: string(fields, "code"),
+            message: string(fields, "message"),
+            ...fields.requestId === undefined ? {} : { requestId: fields.requestId }
+          };
+        }
+      }),
+      cancel: event({
+        wire: "bridge:cancel",
+        from: "app",
+        session: "current",
+        parse: (fields) => ({ id: id(fields) })
+      }),
+      disconnect: event({
+        wire: "bridge:disconnect",
+        from: "app",
+        session: "current",
+        parse: empty
+      }),
+      scriptLoad: event({
+        wire: "script:load",
+        from: "host",
+        session: "current",
+        parse: (fields) => ({ javascript: string(fields, "javascript") })
+      }),
+      stateUpdate: event({
+        wire: "state:update",
+        from: "host",
+        session: "current",
+        parse: (fields) => ({ state: fields.state })
+      }),
+      runtimeLog: event({
+        wire: "runtime:log",
+        from: "app",
+        session: "current",
+        parse: (fields) => {
+          if (!isLogEntry(fields.payload))
+            throw new Error("Invalid log entry.");
+          return { payload: fields.payload };
+        }
+      }),
+      runtimeReady: event({
+        wire: "runtime:ready",
+        from: "app",
+        session: "current",
+        parse: empty
+      }),
+      runtimeError: event({
+        wire: "runtime:error",
+        from: "app",
+        session: "current",
+        parse: empty
+      })
+    }
+  };
+  var byWire = new Map;
+  for (const name of Object.keys(bridgeProtocol.events)) {
+    const wire = bridgeProtocol.events[name].wire;
+    if (byWire.has(wire))
+      throw new Error(\`Duplicate bridge event: \${wire}\`);
+    byWire.set(wire, name);
+  }
+  function bridgeEventName(wire) {
+    return byWire.get(wire);
+  }
+  function parseBridgeEnvelope(value) {
+    if (!value || typeof value !== "object")
+      return;
+    const fields = value;
+    if (fields.channel !== BRIDGE || fields.version !== bridgeProtocol.version || typeof fields.type !== "string" || typeof fields.documentId !== "string" || !fields.documentId || fields.documentId.length > 128 || fields.sessionId !== undefined && !validId(fields.sessionId) || fields.token !== undefined && typeof fields.token !== "string")
+      return;
+    return fields;
+  }
+  function parseBridgePayload(envelope, definition) {
+    try {
+      return {
+        channel: BRIDGE,
+        version: bridgeProtocol.version,
+        documentId: envelope.documentId,
+        ...envelope.sessionId === undefined ? {} : { sessionId: envelope.sessionId },
+        ...envelope.token === undefined ? {} : { token: envelope.token },
+        type: definition.wire,
+        ...definition.parse(envelope)
+      };
+    } catch {
+      return;
+    }
+  }
+  function parseBridgeMessage(value) {
+    const envelope = parseBridgeEnvelope(value);
+    if (!envelope)
+      return;
+    const name = bridgeEventName(envelope.type);
+    if (!name)
+      return;
+    const definition = bridgeProtocol.events[name];
+    if (definition.session !== "none" && envelope.sessionId === undefined)
+      return;
+    return parseBridgePayload(envelope, definition);
+  }
+
+  // src/core/bridge-endpoint.ts
+  function createBridgeEndpoint({
+    role,
+    origin,
+    source,
+    opaque,
+    context,
+    post,
+    diagnostic,
+    invalidRequest,
+    handlers
+  }) {
+    let disposed = false;
+    function send(name, payload) {
+      if (disposed)
+        throw new Error("The bridge endpoint has closed.");
+      const definition = bridgeProtocol.events[name];
+      const current = context();
+      const message = parseBridgeMessage({
+        ...payload,
+        channel: bridgeProtocol.channel,
+        version: bridgeProtocol.version,
+        type: definition.wire,
+        documentId: name === "connect" ? "host" : current.documentId,
+        sessionId: current.sessionId,
+        token: opaque ? current.token : undefined
+      });
+      if (!message || opaque && !validId(current.token))
+        throw new Error("The bridge is not ready to send this event.");
+      diagnostic?.("send", definition.wire);
+      if (disposed)
+        return;
+      post(message);
+    }
+    function receive(event) {
+      const peer = source();
+      if (disposed || !peer || event.origin !== origin || event.source !== peer)
+        return;
+      const envelope = parseBridgeEnvelope(event.data);
+      if (!envelope)
+        return;
+      const current = context();
+      const connecting = role === "app" && envelope.type === bridgeProtocol.events.connect.wire;
+      if (opaque && (connecting ? !validId(envelope.token) : !current.token || envelope.token !== current.token))
+        return;
+      const name = bridgeEventName(envelope.type);
+      if (!name)
+        return;
+      const definition = bridgeProtocol.events[name];
+      if (definition.from === role)
+        return;
+      if (definition.session === "establish") {
+        if (envelope.documentId !== current.documentId || envelope.sessionId === undefined)
+          return;
+      } else if (definition.session === "current") {
+        if (!current.sessionId || envelope.sessionId !== current.sessionId || envelope.documentId !== current.documentId)
+          return;
+      }
+      const message = parseBridgePayload(envelope, definition);
+      if (!message) {
+        if (role === "host" && name === "request" && validId(envelope.id))
+          invalidRequest?.(envelope.id);
+        return;
+      }
+      diagnostic?.("receive", definition.wire);
+      if (disposed)
+        return;
+      const handler = handlers[name];
+      handler(message);
+    }
+    return {
+      send,
+      receive,
+      dispose() {
+        disposed = true;
+      }
+    };
+  }
 
   // src/core/messages.ts
   var errorBrand = Symbol.for("@altertable/data-app/MessageRoutingError");
@@ -193,6 +447,46 @@ var inlineBootstrap = `(() => {
     }
   }
 
+  // src/client/logger.ts
+  function createBridgeLogger(enabled, send) {
+    function resolve(args) {
+      if (args.length === 1 && typeof args[0] === "function") {
+        const value = args[0]();
+        return Array.isArray(value) ? value : [value];
+      }
+      return args.map((arg) => typeof arg === "function" ? arg() : arg);
+    }
+    function write(method, args) {
+      if (!enabled())
+        return;
+      try {
+        send({ method, args: resolve(args) });
+      } catch {}
+    }
+    return {
+      log: (...args) => write("log", args),
+      info: (...args) => write("info", args),
+      warn: (...args) => write("warn", args),
+      error: (...args) => write("error", args)
+    };
+  }
+  function logBridgeMessage(logger, message) {
+    if (message.type === "runtime:log")
+      return;
+    logger.log(() => {
+      const metadata = { type: message.type };
+      if ("id" in message)
+        metadata.id = message.id;
+      if (message.type === "bridge:request") {
+        metadata.route = message.route;
+        const payload = message.payload;
+        if (message.route === "data:query" && payload && typeof payload === "object" && "operation" in payload && typeof payload.operation === "string")
+          metadata.operation = payload.operation;
+      }
+      return ["Sending message to parent", metadata];
+    });
+  }
+
   // src/client/iframe.ts
   function rethrowDataMessageError(error) {
     if (error instanceof MessageRoutingError)
@@ -215,67 +509,61 @@ var inlineBootstrap = `(() => {
     const pending = new Map;
     let hostState;
     const stateListeners = new Set;
-    function send(message) {
-      frame.parent.postMessage({ channel: BRIDGE, version: 1, documentId, sessionId, token, ...message }, parentOrigin);
-    }
+    const logger = createBridgeLogger(() => !disposed && !!sessionId && !!hostState && typeof hostState === "object" && ("logging" in hostState) && hostState.logging === true, (entry) => send("runtimeLog", { payload: entry }));
+    const endpoint = createBridgeEndpoint({
+      role: "app",
+      origin: parentOrigin,
+      source: () => frame.parent,
+      opaque: mode === "bundle",
+      context: () => ({ documentId, sessionId, token }),
+      post(message) {
+        frame.parent.postMessage(message, parentOrigin);
+        logBridgeMessage(logger, message);
+      },
+      handlers: {
+        connect(message) {
+          if (mode === "bundle")
+            token = message.token;
+          send("ready", {});
+        },
+        initialize(message) {
+          if (sessionId && sessionId !== message.sessionId) {
+            for (const entry of pending.values())
+              entry.reject(new DataAppError("The preview reconnected. Retry the request.", "bridge_reset"));
+          }
+          const first = !sessionId;
+          sessionId = message.sessionId;
+          receiveState(message.state);
+          if (first)
+            for (const entry of pending.values())
+              entry.start();
+          if (disposed)
+            return;
+          if (mode === "url")
+            send("runtimeReady", {});
+        },
+        stateUpdate(message) {
+          receiveState(message.state);
+        },
+        scriptLoad(message) {
+          if (mode === "bundle")
+            loadScript?.(message.javascript);
+        },
+        result(message) {
+          pending.get(message.id)?.resolve(message.response);
+        },
+        error(message) {
+          pending.get(message.id)?.reject(new MessageRoutingError(message.code, message.message, message.requestId));
+        }
+      }
+    });
+    const send = endpoint.send;
+    const receive = endpoint.receive;
     function receiveState(state) {
       hostState = state;
       for (const listener of stateListeners)
         listener(state);
     }
-    function receive(event) {
-      if (event.origin !== parentOrigin || event.source !== frame.parent || !isBridgeMessage(event.data))
-        return;
-      const message = event.data;
-      if (message.type === "bridge:connect") {
-        if (mode === "bundle") {
-          if (!validId(message.token))
-            return;
-          token = message.token;
-        }
-        send({ type: "bridge:ready" });
-        return;
-      }
-      if (mode === "bundle" && (!token || message.token !== token))
-        return;
-      if (message.documentId !== documentId)
-        return;
-      if (message.type === "bridge:initialize" && validId(message.sessionId)) {
-        if (sessionId && sessionId !== message.sessionId) {
-          for (const entry of pending.values())
-            entry.reject(new DataAppError("The preview reconnected. Retry the request.", "bridge_reset"));
-        }
-        const first = !sessionId;
-        sessionId = message.sessionId;
-        if (first)
-          for (const entry of pending.values())
-            entry.start();
-        receiveState(message.state);
-        if (mode === "url")
-          send({ type: "runtime:ready" });
-        return;
-      }
-      if (!sessionId || message.sessionId !== sessionId)
-        return;
-      if (message.type === "state:update") {
-        receiveState(message.state);
-        return;
-      }
-      if (message.type === "script:load" && mode === "bundle" && typeof message.javascript === "string") {
-        loadScript?.(message.javascript);
-        return;
-      }
-      if (typeof message.id !== "string")
-        return;
-      const entry = pending.get(message.id);
-      if (!entry)
-        return;
-      if (message.type === "bridge:result" && "response" in message) {
-        entry.resolve(message.response);
-      } else if (message.type === "bridge:error" && typeof message.code === "string" && typeof message.message === "string") {
-        entry.reject(new MessageRoutingError(message.code, message.message, typeof message.requestId === "string" ? message.requestId : undefined));
-      }
-    }
     frame.addEventListener("message", receive);
     function requestMessage(message, signal) {
       return new Promise((resolve, reject) => {
@@ -294,13 +582,13 @@ var inlineBootstrap = `(() => {
         }
         function abort() {
           if (sent)
-            send({ type: "bridge:cancel", id });
+            send("cancel", { id });
           cleanup();
           reject(signal?.reason);
         }
         const timer = setTimeout(() => {
           if (sent)
-            send({ type: "bridge:cancel", id });
+            send("cancel", { id });
           cleanup();
           reject(new DataAppError(sessionId ? "The data request timed out." : "The preview shell is unavailable. Reload the preview.", sessionId ? "timeout" : "bridge_unavailable"));
         }, timeoutMs);
@@ -309,8 +597,7 @@ var inlineBootstrap = `(() => {
             if (sent)
               return;
             try {
-              send({
-                type: "bridge:request",
+              send("request", {
                 id,
                 route: message.route,
                 payload: message.payload
@@ -334,8 +621,8 @@ var inlineBootstrap = `(() => {
         signal?.addEventListener("abort", abort, { once: true });
         if (sessionId)
           entry.start();
-        else
-          send({ type: "bridge:ready" });
+        else if (mode === "url" || token)
+          send("ready", {});
       });
     }
     const messages = createMessageClient({ "data:query": defineDataQueryRoute(), "data:sql": sqlQueryRoute }, requestMessage);
@@ -343,20 +630,22 @@ var inlineBootstrap = `(() => {
       return messages.request("data:query", { operation, input }, { signal }).catch(rethrowDataMessageError);
     }
     function disconnect() {
-      send({ type: "bridge:disconnect" });
+      if (sessionId)
+        send("disconnect", {});
       sessionId = undefined;
       for (const entry of pending.values())
         entry.reject(new DataAppError("The preview has closed.", "bridge_closed"));
     }
     function resume(event) {
-      if (event.persisted)
-        send({ type: "bridge:ready" });
+      if (event.persisted && (mode === "url" || token))
+        send("ready", {});
     }
     function dispose() {
       if (disposed)
         return;
       disconnect();
       disposed = true;
+      endpoint.dispose();
       frame.removeEventListener("message", receive);
       frame.removeEventListener("pagehide", disconnect);
       frame.removeEventListener("pageshow", resume);
@@ -365,8 +654,9 @@ var inlineBootstrap = `(() => {
     frame.addEventListener("pagehide", disconnect);
     frame.addEventListener("pageshow", resume);
     if (mode === "url")
-      send({ type: "bridge:ready" });
+      send("ready", {});
     return {
+      logger,
       request: requestMessage,
       transport: queryOperation,
       lakehouse: {
@@ -386,10 +676,12 @@ var inlineBootstrap = `(() => {
         };
       },
       ready() {
-        send({ type: "runtime:ready" });
+        if (!disposed && sessionId)
+          send("runtimeReady", {});
       },
       fail() {
-        send({ type: "runtime:error" });
+        if (!disposed && sessionId)
+          send("runtimeError", {});
       }
     };
   }
@@ -417,6 +709,7 @@ var inlineBootstrap = `(() => {
   }) {
     let loaded;
     let failed = false;
+    const bundleSource = \`altertable-data-app-\${crypto.randomUUID()}.js\`;
     const bridge = createIframeTransport({
       parentOrigin,
       window: frame,
@@ -435,7 +728,8 @@ var inlineBootstrap = `(() => {
         loaded = javascript;
         try {
           const script = frame.document.createElement("script");
-          script.textContent = javascript;
+          script.textContent = \`\${javascript}
+//# sourceURL=\${bundleSource}\`;
           frame.document.body.append(script);
           if (!failed)
             bridge.ready();
@@ -448,12 +742,20 @@ var inlineBootstrap = `(() => {
       failed = true;
       bridge.fail();
     }
-    frame.addEventListener("error", reportError);
-    frame.addEventListener("unhandledrejection", reportError);
+    function reportBundleError(event) {
+      if (event.filename === bundleSource)
+        reportError();
+    }
+    function reportBundleRejection(event) {
+      if (event.reason instanceof Error && event.reason.stack?.includes(bundleSource))
+        reportError();
+    }
+    frame.addEventListener("error", reportBundleError);
+    frame.addEventListener("unhandledrejection", reportBundleRejection);
     const uninstall = installDataAppTransport(bridge, frame);
     return () => {
-      frame.removeEventListener("error", reportError);
-      frame.removeEventListener("unhandledrejection", reportError);
+      frame.removeEventListener("error", reportBundleError);
+      frame.removeEventListener("unhandledrejection", reportBundleRejection);
       uninstall();
     };
   }
@@ -486,6 +788,7 @@ function isPreviewHost(hostname, domainName) {
   return hostname.endsWith(suffix) && TOKEN_RE.test(hostname.slice(0, -suffix.length));
 }
 var worker_default = {
+  runtimeHtml,
   fetch(request, env) {
     const url = new URL(request.url);
     if (!isPreviewHost(url.hostname, env.DOMAIN_NAME) || url.pathname !== "/") {

package/docs/app-authoring.md

@@ -1,7 +1,9 @@
 # Author a data app
 
 Build an exploration that answers the user's question and a story that presents
-its strongest findings. Both use the same queries, definitions, and evidence.
+its strongest findings. Include CSV export so readers can take the displayed
+results into their own tools. Exploration, export, and story use the same
+queries, definitions, and evidence.
 
 ## Inspect the data
 
@@ -38,10 +40,31 @@ and failure.
 | Register source names                      | [Source identifiers](react.md#register-source-identifiers) |
 | Choose date and field filters              | [Filter variables](react.md#time-views-and-field-filters)  |
 | Handle refresh and stale results           | [Displayed results](react.md#preserve-displayed-results)   |
+| Export displayed data as CSV               | [CSV export](react.md#export-displayed-data-as-csv)        |
 | Bind definitions and source evidence       | [Data context](react.md#bind-evidence)                     |
 
 Use the exported types for configuration, appearance, formatting, and component
-options.
+options. Declare configuration with `satisfies DataAppConfig` so appearance
+fields and values are checked before bundling.
+
+## Compose the layout
+
+See the [layout contract](layout.md).
+
+## Export the displayed results
+
+Provide `DataApp.csvExport` in every analytical app. The request-backed API
+requires a callback that selects an explicit filename and named datasets with ordered columns and raw
+rows from the displayed snapshot. Follow [CSV export](react.md#export-displayed-data-as-csv)
+and the [starter](../examples/starter-data-app/index.tsx); use the built-in toolbar
+action rather than adding a custom download button.
+
+Export every distinct analytical dataset at its displayed grain, including relevant
+dimensions and measures. Reuse one dataset for charts or metrics derived from the
+same rows. One dataset downloads as CSV; multiple datasets offer individual CSVs
+and **Export all** as a ZIP archive. Use the displayed input for scope labels and filenames. Export the
+bounded result the app already has; do not issue a different query or mix pending
+filters into the visible result. Setup and static screens may omit export.
 
 ## Present the findings
 
@@ -54,7 +77,11 @@ row or chart into a step.
 
 Verify findings against the source and the user's question. Distinguish measured
 zero, unavailable values, and empty results. Check filters, refresh, loading,
-empty, error, and stale states, then present the story. Inspect both experiences
+empty, error, and stale states, then present the story. Download CSV from the
+standalone and embedded toolbar and verify its filename, columns, raw values,
+and filter scope against the displayed result. Export and Present story must be
+available once analytical results are shown; initial loading, empty, and initial
+errors have neither action. Inspect both experiences
 at phone and desktop widths in light and dark themes.
 
 The app owns its queries, result parsing, business definitions, configuration,

package/docs/embed.md

@@ -73,7 +73,7 @@ app bundle; non-React apps use `createDataAppNavigation()` from `/client`.
 
 `attachDataAppBridge()` also supports connection mode for a host-owned iframe. Supply
 `connection: { type: 'origin', origin }` or `{ type: 'opaque', token }`, and an
-`onMessage` dispatcher. Both modes use the same transport. It returns `dispose()` and `setPresentation()` methods and owns source/origin checks, request
+`onMessage` dispatcher. Both modes use the same transport. It returns `dispose()`, `setPresentation()`, and `setLogger()` methods and owns source/origin checks, request
 correlation, cancellation, bounded pending requests, and reconnection. Use source mode for bundle loading and token rotation. The opaque destination requires
 wildcard delivery, but incoming messages still require the exact iframe window,
 null origin, token, document, and session to match.

package/docs/hosted-apps.md

@@ -4,7 +4,7 @@ Follow the [shared authoring flow](app-authoring.md) using [index.tsx](../exampl
 one file with public package imports; omit server files, HTML, credentials, and
 relative or app-alias imports.
 
-Replace the sample SQL, parsers, filters, data context, story, and configuration with
+Replace the sample SQL, parsers, filters, data context, CSV export, story, and configuration with
 an exploration of the source data you inspected. The starter uses two SQL
 `VALUES` rows, so it needs no production table.
 
@@ -13,7 +13,7 @@ For execution details, see [browser-owned operations](client.md#browser-owned-op
 ## Convert a local data app
 
 1. Combine the app's operations and parsers, data context, views, story,
-   configuration, and browser entry into one `index.tsx`, following the
+   CSV export, configuration, and browser entry into one `index.tsx`, following the
    [single-file starter](../examples/starter-data-app/index.tsx).
 2. Replace the HTTP client with `createDataClient({ operations })`, using the
    operation registry as a value. See [browser-owned operations](client.md#browser-owned-operations-for-bundle-apps)