@altertable/data-app 0.64.0 → 0.66.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();
     };
   }

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
 
@@ -25,39 +27,71 @@ readers can inspect the source of each claim.
 
 Connect visualizations with introductions and explanations. Use `<TextWidget>`
 for a narrative panel with the standard widget frame, or `<TextContent>` for
-borderless prose. Bind claims to `result.select((data, input) => ...)` so their
-values and scope follow the displayed results through filter changes, refresh,
-and failure.
-
-| Task                                       | Documentation                                              |
-| ------------------------------------------ | ---------------------------------------------------------- |
-| Define queries, inputs, and result parsing | [Operations](contract.md)                                  |
-| Build views, filters, and request states   | [React](react.md)                                          |
-| Introduce and explain visualizations       | [Narrative text](react.md#narrative-text)                  |
-| Find formatters and presentation helpers   | [App helpers](react.md#reuse-app-helpers)                  |
-| 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)   |
-| Bind definitions and source evidence       | [Data context](react.md#bind-evidence)                     |
-
-Use the exported types for configuration, appearance, formatting, and component
-options. Declare configuration with `satisfies DataAppConfig` so appearance
-fields and values are checked before bundling.
-
-## Present the findings
-
-Compose a [story](react.md#present-data-with-stories) from the exploration's
-findings. Lead with the answer, then show the evidence and comparisons that
-explain it. Select the findings that matter to the audience; do not turn every
-row or chart into a step.
+borderless prose. Render static titles, descriptions, and instructions immediately. Use metric and dataset
+bindings for dynamic values and `<DataValue>` for values within static prose.
+Skeletonize only the content that needs data. Reuse bindings and the displayed
+source in narrative so values, formatting, and evidence follow filter changes,
+refresh, and failure.
+
+| Task                                             | Documentation                                                     |
+| ------------------------------------------------ | ----------------------------------------------------------------- |
+| Choose components, CSS tokens, and styling hooks | [Styling](styling.md)                                             |
+| Define queries, inputs, and result parsing       | [Operations](contract.md)                                         |
+| Build views, filters, and request states         | [Views](views.md)                                                 |
+| Introduce and explain visualizations             | [Narrative text](widgets.md#narrative-text)                       |
+| Find formatters and presentation helpers         | [App helpers](formatting-and-appearance.md)                       |
+| Register source names                            | [Source identifiers](data-context.md#register-source-identifiers) |
+| Choose date and field filters                    | [Filter variables](variables.md)                                  |
+| Handle refresh and stale results                 | [Displayed results](views.md#preserve-displayed-results)          |
+| Export displayed data as CSV                     | [CSV export](stories-and-export.md#export-displayed-data-as-csv)  |
+| Render widgets and custom visuals                | [Widgets](widgets.md)                                             |
+| Bind definitions and source evidence             | [Data context](data-context.md#bind-evidence)                     |
+
+Declare reusable [datasets and metrics](widgets.md#declare-datasets-and-metrics)
+on the view so tables, exports, and stories share values and evidence.
+
+Every data app supplies a [story and CSV export](stories-and-export.md)
+from the displayed result. Export all distinct datasets at their displayed grain;
+reuse a dataset when several visuals derive from the same rows. Present the
+findings that answer the reader's question, rather than every row or chart.
+Use the [standard layout](layout.md) and built-in toolbar actions.
+
+### Organize the exploration
+
+Use sections for a focused question and for findings readers should compare
+side by side. Add app-level `<Tabs>` from `/react/ui` when the exploration has
+distinct analytical questions, such as Overview, Retention, and Segments, each
+with its own context and group of widgets. Lead with the most useful overview
+and label tabs by the question or subject they explore.
+
+Use `<VisualizationWidget>`'s `views` for alternate representations of the same
+dataset, such as a chart and its rows. Keep these choices within the widget;
+use filter variables when the reader is changing the data scope.
+
+Navigation tabs, widget views, and declared data views have different roles.
+A declared view owns inputs, requests, and displayed results; a tab does not
+require a separate data view. Keep related datasets in one view for a coherent
+snapshot. Use independent views and `<DataSection>` boundaries when content
+needs separate requests. Keep filter placement consistent across tabs and make
+each filter's scope clear. Derive findings, story, and export from the displayed
+results and their inputs.
+
+Choose each visual for the question it answers; see
+[visualization selection](widgets.md#choose-a-visualization).
 
 ## Verify the app
 
+Follow the [UI quality contract](ui-quality.md) for hierarchy, responsive
+composition, typography, and control states.
+
 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 results are shown; initial loading, empty, and initial
+errors keep both actions visible and disabled. Inspect both experiences
 at phone and desktop widths in light and dark themes.
 
-The app owns its queries, result parsing, business definitions, configuration,
-and presentation. Credentials, authorization, and enforced access/query limits
-stay backend-owned. Edit app-owned files; installed package files are dependencies.
+Keep credentials, authorization, and enforced query limits in the host/backend.
+Edit app-owned files; installed package files are dependencies.