@marimo-team/islands 0.25.3-dev290 → 0.25.3-dev291

package/src/core/executions/hooks.ts

@@ -5,8 +5,14 @@ import { dequal } from "dequal";
 import { useAtomValue } from "jotai";
 import { selectAtom } from "jotai/utils";
 import { useMemo } from "react";
-import { cellExecutionInputsAtom, cellFreshnessAtom } from "./atoms";
+import { parseOutline } from "@/core/dom/outline";
+import {
+  cellExecutionInputsAtom,
+  cellFreshnessAtom,
+  cellOutputInputsAtom,
+} from "./atoms";
 import type { CellFreshness } from "./freshness";
+import { type CellOutput, cellOutputView, scratchOutputView } from "./output";
 import { type CellExecutionView, cellExecutionView } from "./select";
 
 /**
@@ -32,11 +38,10 @@ export function useCellExecution(id: Protocol.CellId): CellExecutionView {
 }
 
 /**
- * Whether a cell's result is current, by the host protocol's rules over
- * the confirmed document and the executions mirror.
+ * Whether a cell's result is current, by the host protocol's rules.
  *
- * The confirmed document is what the host has accepted, so an edit reads
- * as such once the model has flushed it, not on the keystroke.
+ * The comparison reads the confirmed document, so an edit counts once the
+ * host has it, not on the keystroke.
  */
 export function useCellFreshness(id: Protocol.CellId): CellFreshness {
   const cellAtom = useMemo(
@@ -45,3 +50,37 @@ export function useCellFreshness(id: Protocol.CellId): CellFreshness {
   );
   return useAtomValue(cellAtom);
 }
+
+/** What the cell shows: its running value so far, else its result's outcome. */
+export function useCellOutput(id: Protocol.CellId): CellOutput | null {
+  const cellAtom = useMemo(
+    () =>
+      selectAtom(
+        cellOutputInputsAtom,
+        (inputs) => cellOutputView(inputs, id),
+        dequal,
+      ),
+    [id],
+  );
+  return useAtomValue(cellAtom);
+}
+
+/** The headings in the cell's output, for the table of contents. */
+export function useCellOutline(id: Protocol.CellId) {
+  const output = useCellOutput(id);
+  return useMemo(() => parseOutline(output), [output]);
+}
+
+/** What the scratchpad shows, from its latest scratch execution. */
+export function useScratchOutput(): CellOutput | null {
+  const scratchAtom = useMemo(
+    () =>
+      selectAtom(
+        cellOutputInputsAtom,
+        (inputs) => scratchOutputView(inputs.executions),
+        dequal,
+      ),
+    [],
+  );
+  return useAtomValue(scratchAtom);
+}

package/src/core/executions/index.ts

@@ -11,6 +11,8 @@
 export {
   cellExecutionInputsAtom,
   cellFreshnessAtom,
+  cellOutputInputsAtom,
+  clearCellOutputs,
   notebookIsRunningAtom,
   notebookQueuedOrRunningCountAtom,
   observeCellMessage,
@@ -20,7 +22,20 @@ export {
   withdrawCells,
 } from "./atoms";
 export type { CellFreshness, CellFreshnessLookup } from "./freshness";
-export { useCellExecution, useCellFreshness } from "./hooks";
+export {
+  useCellExecution,
+  useCellFreshness,
+  useCellOutline,
+  useCellOutput,
+  useScratchOutput,
+} from "./hooks";
+export {
+  type CellError,
+  type CellOutput,
+  cellOutputView,
+  type HostDiagnostic,
+  scratchOutputView,
+} from "./output";
 export {
   type CellExecutionInputs,
   type CellExecutionView,

package/src/core/executions/output.ts

@@ -0,0 +1,242 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/**
+ * What a cell shows in its output area, read from the host's executions.
+ *
+ * A completed result's outcome is the output. While the cell runs again,
+ * the running execution's value so far takes its place, so appended
+ * output appears as it arrives. The view keeps the message shape the
+ * renderers take, so they need not know where it came from.
+ */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { CellId } from "@/core/cells/ids";
+import type { MarimoError, OutputMessage } from "@/core/kernel/messages";
+import type { Executions, Results } from "@/core/notebook/replica";
+
+/** A host error shown as its message and the cells involved. */
+export interface HostDiagnostic {
+  readonly type: "diagnostic";
+  readonly kind: string;
+  readonly msg: string;
+  readonly related: readonly {
+    readonly cell_id: CellId;
+    readonly message: string;
+  }[];
+}
+
+/** An error the output area renders: a kernel shape or a host diagnostic. */
+export type CellError = MarimoError | HostDiagnostic;
+
+/** An output message whose error data may carry host diagnostics. */
+export type CellOutput = Omit<OutputMessage, "data"> & {
+  readonly data: OutputMessage["data"] | readonly CellError[];
+};
+
+/** What every cell's output derives from. */
+export interface CellOutputInputs {
+  readonly executions: Executions;
+  readonly results: Results;
+  /** Results this browser cleared, by execution id, until a newer one lands. */
+  readonly cleared: ReadonlyMap<Protocol.CellId, Protocol.ExecutionId>;
+}
+
+const ERROR_MIMETYPE = "application/vnd.marimo+error";
+
+/** The protocol's ids are plain strings; the editor brands them. */
+function brand(id: Protocol.CellId): CellId {
+  return id as CellId;
+}
+
+function related(
+  cells: readonly Protocol.Related[],
+): HostDiagnostic["related"] {
+  return cells.map(({ cell_id, message }) => ({
+    cell_id: brand(cell_id),
+    message,
+  }));
+}
+
+function seconds(iso: string | null): number {
+  return iso === null ? 0 : Date.parse(iso) / 1000;
+}
+
+function endedAt(record: Protocol.Execution): number {
+  return seconds(record.completed_at ?? record.started_at);
+}
+
+function valueOutput(
+  record: Protocol.Execution,
+  value: Protocol.DisplayData,
+): CellOutput {
+  return {
+    channel: "output",
+    mimetype: value.mimetype as OutputMessage["mimetype"],
+    data: value.data,
+    timestamp: endedAt(record),
+  };
+}
+
+function errorOutput(
+  record: Protocol.Execution,
+  data: CellError[],
+): CellOutput {
+  return {
+    channel: "marimo-error",
+    mimetype: ERROR_MIMETYPE,
+    data,
+    timestamp: endedAt(record),
+  };
+}
+
+/** The cell an exception was blamed on, when the host names one. */
+function raisingCell(error: Protocol.Error): CellId | null {
+  const raised = error.related.find((cell) => cell.message === "raised");
+  return raised === undefined ? null : brand(raised.cell_id);
+}
+
+/**
+ * A host error in the shape the output area renders.
+ *
+ * Exceptions, syntax errors, and internal errors keep the kernel's shapes,
+ * which the renderer treats with their own affordances. Every other kind
+ * is a diagnostic.
+ */
+export function cellError(error: Protocol.Error): CellError {
+  switch (error.kind) {
+    case "exception":
+      return {
+        type: "exception",
+        exception_type: error.name ?? "Exception",
+        msg: error.message,
+        raising_cell: raisingCell(error),
+        traceback: error.traceback?.data ?? null,
+      };
+    case "invalid-syntax":
+      return {
+        type: "syntax",
+        msg: error.message,
+        lineno: error.range === null ? null : error.range.start.line + 1,
+      };
+    case "internal":
+      return { type: "unknown", msg: error.message, error_type: error.name };
+    case "interrupted":
+      return { type: "interruption" };
+    default:
+      return {
+        type: "diagnostic",
+        kind: error.kind,
+        msg: error.message,
+        related: related(error.related),
+      };
+  }
+}
+
+/** The notice a skipped cell shows in place of a value. */
+function skippedOutput(
+  record: Protocol.Execution,
+  outcome: Protocol.SkippedOutcome,
+): CellOutput {
+  const cause = outcome.related[0];
+  if (cause !== undefined && outcome.reason === "upstream-stopped") {
+    return errorOutput(record, [
+      {
+        type: "ancestor-stopped",
+        msg: outcome.message,
+        raising_cell: brand(cause.cell_id),
+      },
+    ]);
+  }
+  if (cause !== undefined && outcome.reason === "upstream-failed") {
+    const blamed = outcome.related
+      .slice(1)
+      .find((cell) => cell.cell_id !== record.cell_id);
+    return errorOutput(record, [
+      {
+        type: "ancestor-prevented",
+        msg: outcome.message,
+        raising_cell: brand(cause.cell_id),
+        blamed_cell: blamed === undefined ? null : brand(blamed.cell_id),
+      },
+    ]);
+  }
+  return errorOutput(record, [
+    {
+      type: "diagnostic",
+      kind: outcome.reason,
+      msg: outcome.message,
+      related: related(outcome.related),
+    },
+  ]);
+}
+
+/** What an execution's outcome shows, or null for an empty value. */
+export function outcomeOutput(record: Protocol.Execution): CellOutput | null {
+  const outcome = record.outcome;
+  if (outcome === null) {
+    return null;
+  }
+  switch (outcome.kind) {
+    case "value":
+      return outcome.display === null
+        ? null
+        : valueOutput(record, outcome.display);
+    case "error":
+      return errorOutput(record, [cellError(outcome.error)]);
+    case "interrupted":
+      return errorOutput(record, [{ type: "interruption" }]);
+    case "skipped":
+      return skippedOutput(record, outcome);
+  }
+}
+
+/**
+ * What a cell shows: its running value so far, else its result's outcome.
+ *
+ * A running execution's outcome is null until it shows something, so the
+ * result stays up until then. Once it has shown, an empty display means
+ * the cell cleared its output, and nothing shows.
+ */
+export function cellOutputView(
+  inputs: CellOutputInputs,
+  id: Protocol.CellId,
+): CellOutput | null {
+  const latestId = inputs.executions.latest.get(id);
+  const latest =
+    latestId === undefined
+      ? undefined
+      : inputs.executions.executions.get(latestId)?.record;
+  if (latest !== undefined && latest.outcome !== null) {
+    if (latest.status !== "completed") {
+      return outcomeOutput(latest);
+    }
+  }
+  const result = inputs.results.get(id);
+  if (result === null || result === undefined) {
+    return null;
+  }
+  if (inputs.cleared.get(id) === result.id) {
+    return null;
+  }
+  return outcomeOutput(result);
+}
+
+/** What the scratchpad shows, from its latest scratch execution. */
+export function scratchOutputView(executions: Executions): CellOutput | null {
+  let scratch: Protocol.Execution | undefined;
+  for (const { record } of executions.executions.values()) {
+    if (record.cell_id !== null) {
+      continue;
+    }
+    if (
+      scratch === undefined ||
+      seconds(record.started_at) >= seconds(scratch.started_at)
+    ) {
+      scratch = record;
+    }
+  }
+  if (scratch === undefined) {
+    return null;
+  }
+  return outcomeOutput(scratch);
+}