Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

add speaker notes for slides (#9533)

Shahmir Varqha6492353ebc6e
diff --git a/docs/guides/apps.md b/docs/guides/apps.md
index 14551a44ed..1f2747343b 100644
--- a/docs/guides/apps.md
+++ b/docs/guides/apps.md
@@ -87,7 +87,8 @@ If you prefer a slideshow-like experience, you can use the slides layout. Enable
- A slide minimap on the left where you can drag and drop slides to rearrange them.
- A config sidebar on the right where you can configure the type of each slide.
-- Edit code and run cells by clicking the Code toggle or using the keyboard shortcut `C`.
+- Edit code and run cells by clicking the Code toggle or pressing `C`.
+- Add speaker notes at the bottom of each slide and launch speaker view by pressing `S`.
- Powered by [reveal.js](https://revealjs.com/), so you can use most of its features like keyboard shortcuts, navigation, etc.
#### Notes
diff --git a/frontend/e2e-tests/slides.spec.ts b/frontend/e2e-tests/slides.spec.ts
index 9497ccc9b8..59ab91dbd4 100644
--- a/frontend/e2e-tests/slides.spec.ts
+++ b/frontend/e2e-tests/slides.spec.ts
@@ -30,8 +30,9 @@ test("slides", async ({ page }) => {
await takeScreenshot(page, __filename);
- // Reveal.js marks the active slide <section> with .present
- const slides = slidesContainer.locator(".slides > section");
+ // Reveal.js marks the active slide <section> with .present. We match by
+ // `data-index-h` (which reveal sets on each slide section)
+ const slides = slidesContainer.locator("section[data-index-h]");
await expect(slides.first()).toHaveClass(/present/);
// Focus the deck so keyboard navigation works (embedded mode)
diff --git a/frontend/src/components/editor/renderers/slides-layout/__tests__/compute-slide-cells.test.ts b/frontend/src/components/editor/renderers/slides-layout/__tests__/compute-slide-cells.test.ts
index 38097f45e8..497c4f9185 100644
--- a/frontend/src/components/editor/renderers/slides-layout/__tests__/compute-slide-cells.test.ts
+++ b/frontend/src/components/editor/renderers/slides-layout/__tests__/compute-slide-cells.test.ts
@@ -4,6 +4,7 @@ import { describe, it, expect } from "vitest";
import { computeSlideCellsInfo } from "../compute-slide-cells";
import type { SlideConfig, SlidesLayout } from "../types";
import type { CellId } from "@/core/cells/ids";
+import { cellId } from "@/__tests__/branded";
interface TestCell {
id: CellId;
@@ -15,10 +16,10 @@ const DEFAULT_OUTPUT: TestCell["output"] = { data: "ok" };
const cell = (
id: string,
output: TestCell["output"] = DEFAULT_OUTPUT,
-): TestCell => ({ id: id as CellId, output });
+): TestCell => ({ id: cellId(id), output });
const layoutOf = (entries: Array<[string, SlideConfig]>): SlidesLayout => ({
- cells: new Map(entries.map(([id, cfg]) => [id as CellId, cfg])),
+ cells: new Map(entries.map(([id, cfg]) => [cellId(id), cfg])),
deck: {},
});
@@ -121,7 +122,7 @@ describe("computeSlideCellsInfo", () => {
// Skipped cells are still "visible" deck cells — they just aren't rendered
// in reveal. The minimap relies on the full list plus skippedIds.
expect(result.cellsWithOutput.map((c) => c.id)).toEqual(["a", "b", "c"]);
- expect(result.slideTypes.get("b" as CellId)).toBe("skip");
+ expect(result.slideTypes.get(cellId("b"))).toBe("skip");
});
it("ignores layout entries for cells that have no output", () => {
@@ -137,7 +138,7 @@ describe("computeSlideCellsInfo", () => {
);
expect(result.cellsWithOutput.map((c) => c.id)).toEqual(["a"]);
expect(result.skippedIds.size).toBe(0);
- expect(result.slideTypes.has("b" as CellId)).toBe(false);
+ expect(result.slideTypes.has(cellId("b"))).toBe(false);
});
it("preserves the input order of cells in cellsWithOutput", () => {
diff --git a/frontend/src/components/editor/renderers/slides-layout/__tests__/plugin.test.ts b/frontend/src/components/editor/renderers/slides-layout/__tests__/plugin.test.ts
index 74b63cb49b..dd8a36d4a8 100644
--- a/frontend/src/components/editor/renderers/slides-layout/__tests__/plugin.test.ts
+++ b/frontend/src/components/editor/renderers/slides-layout/__tests__/plugin.test.ts
@@ -4,10 +4,11 @@ import { describe, it, expect } from "vitest";
import { SlidesLayoutPlugin } from "../plugin";
import type { CellData } from "@/core/cells/types";
import type { CellId } from "@/core/cells/ids";
+import { cellId } from "@/__tests__/branded";
function makeCell(id: string, code = "print('hi')"): CellData {
return {
- id: id as CellId,
+ id: cellId(id),
name: id,
code,
edited: false,
@@ -198,7 +199,10 @@ const BACKWARDS_COMPAT_SNAPSHOTS: BackwardsCompatCase[] = [
},
{
// Defensive: if a future version adds a new SlideConfig field and a user
- // downgrades, we must not crash on unknown keys.
+ // downgrades, we must not crash on unknown keys — AND we must not silently
+ // drop them either. `notes` / `background` aren't in the current schema;
+ // they must still be present after validate + (de)serialize so a downgrade
+ // followed by a save doesn't erase the newer marimo's data.
label: "forward-compat: unknown SlideConfig fields present",
input: {
cells: [{ type: "slide", notes: "x", background: "#000" }],
@@ -206,7 +210,42 @@ const BACKWARDS_COMPAT_SNAPSHOTS: BackwardsCompatCase[] = [
expected: {
deck: {},
cellIds: ["a"],
- cellEntries: [["a", { type: "slide" }]],
+ cellEntries: [["a", { type: "slide", notes: "x", background: "#000" }]],
+ },
+ },
+ {
+ // Same forward-compat guarantee for unknown deck-level fields (e.g. future
+ // Reveal options we haven't modeled yet).
+ label: "forward-compat: unknown deck fields present",
+ input: {
+ cells: [{}],
+ deck: { transition: "fade", controls: false, autoSlide: 5000 },
+ },
+ expected: {
+ deck: { transition: "fade", controls: false, autoSlide: 5000 },
+ cellIds: ["a"],
+ },
+ },
+ {
+ // `speakerNotes` was added to SlideConfig. The validator must
+ // know about it (so it isn't silently stripped), the deserializer must
+ // carry it through, and serialize → deserialize must round-trip it.
+ label: "speakerNotes round-trips through validate + (de)serialize",
+ input: {
+ cells: [
+ { type: "slide", speakerNotes: "intro" },
+ { type: "fragment", speakerNotes: "" },
+ { type: "fragment", speakerNotes: "multi\n\nline\n\nnotes" },
+ ],
+ },
+ expected: {
+ deck: {},
+ cellIds: ["a", "b", "c"],
+ cellEntries: [
+ ["a", { type: "slide", speakerNotes: "intro" }],
+ ["b", { type: "fragment", speakerNotes: "" }],
+ ["c", { type: "fragment", speakerNotes: "multi\n\nline\n\nnotes" }],
+ ],
},
},
];
@@ -223,20 +262,21 @@ describe("SlidesLayoutPlugin backwards compatibility", () => {
parsed.success,
`validator rejected: ${JSON.stringify(input)}`,
).toBe(true);
+ if (!parsed.success) {
+ return;
+ }
- // 2. Deserialize must succeed and reflect the user-set fields.
- const layout = SlidesLayoutPlugin.deserializeLayout(
- // Use the raw input (not the validator output) because that is what
- // `deserializeLayout` actually receives in production today.
- // oxlint-disable-next-line typescript/no-explicit-any
- input as any,
- cells,
- );
+ // 2. Deserializing the *validator output* (not the raw input) must
+ // preserve every field listed in `expected.cellEntries`. This is what
+ // catches a schema regression: if the validator silently strips a
+ // known field, the deserialized config won't carry it and the
+ // assertion below fails.
+ const layout = SlidesLayoutPlugin.deserializeLayout(parsed.data, cells);
if (expected.deck !== undefined) {
expect(layout.deck).toEqual(expected.deck);
}
- for (const [cellId, expectedConfig] of expected.cellEntries ?? []) {
- expect(layout.cells.get(cellId as CellId)).toMatchObject(
+ for (const [cellEntryId, expectedConfig] of expected.cellEntries ?? []) {
+ expect(layout.cells.get(cellId(cellEntryId))).toMatchObject(
expectedConfig as object,
);
}
@@ -251,8 +291,8 @@ describe("SlidesLayoutPlugin backwards compatibility", () => {
reserialized,
cells,
);
- for (const [cellId, expectedConfig] of expected.cellEntries ?? []) {
- expect(redeserialized.cells.get(cellId as CellId)).toMatchObject(
+ for (const [cellEntryId, expectedConfig] of expected.cellEntries ?? []) {
+ expect(redeserialized.cells.get(cellId(cellEntryId))).toMatchObject(
expectedConfig as object,
);
}
diff --git a/frontend/src/components/editor/renderers/slides-layout/plugin.tsx b/frontend/src/components/editor/renderers/slides-layout/plugin.tsx
index 0435c2ac00..2f9c7b81d0 100644
--- a/frontend/src/components/editor/renderers/slides-layout/plugin.tsx
+++ b/frontend/src/components/editor/renderers/slides-layout/plugin.tsx
@@ -1,15 +1,15 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import { z } from "zod";
+import type { CellId } from "@/core/cells/ids";
+import { Logger } from "@/utils/Logger";
import type { ICellRendererPlugin } from "../types";
import { SlidesLayoutRenderer } from "./slides-layout";
-import type {
- SerializedSlidesLayout,
- SlideConfig,
- SlidesLayout,
+import {
+ type SerializedSlidesLayout,
+ type SlideConfig,
+ type SlidesLayout,
+ SlidesLayoutSchema,
} from "./types";
-import { Logger } from "@/utils/Logger";
-import type { CellId } from "@/core/cells/ids";
/**
* Plugin definition for the slides layout.
@@ -20,24 +20,7 @@ export const SlidesLayoutPlugin: ICellRendererPlugin<
> = {
type: "slides",
name: "Slides",
-
- // All fields are optional so layouts saved by older marimo versions will work
- validator: z.object({
- cells: z
- .array(
- z.object({
- type: z.enum(["slide", "sub-slide", "fragment", "skip"]).optional(),
- }),
- )
- .optional(),
- deck: z
- .object({
- transition: z
- .enum(["none", "fade", "slide", "convex", "concave", "zoom"])
- .optional(),
- })
- .optional(),
- }),
+ validator: SlidesLayoutSchema,
deserializeLayout: (serialized, cells): SlidesLayout => {
const serializedCells = serialized.cells ?? [];
diff --git a/frontend/src/components/editor/renderers/slides-layout/slides-layout.tsx b/frontend/src/components/editor/renderers/slides-layout/slides-layout.tsx
index 6f152c1df6..9b4c1edad5 100644
--- a/frontend/src/components/editor/renderers/slides-layout/slides-layout.tsx
+++ b/frontend/src/components/editor/renderers/slides-layout/slides-layout.tsx
@@ -3,6 +3,7 @@ import React, { useMemo, useState } from "react";
import { useAtomValue } from "jotai";
import { numColumnsAtom } from "@/core/cells/cells";
import type { CellId } from "@/core/cells/ids";
+import { kioskModeAtom } from "@/core/mode";
import type { ICellRendererProps } from "../types";
import type { SlidesLayout } from "./types";
import { computeSlideCellsInfo } from "./compute-slide-cells";
@@ -21,7 +22,10 @@ export const SlidesLayoutRenderer: React.FC<Props> = ({
cells,
mode,
}) => {
- const isReading = mode === "read";
+ // Kiosk clients (e.g. reveal.js's speaker-view iframes) are read-only and
+ // shouldn't show authoring chrome, so we collapse to the read-mode layout.
+ const kioskMode = useAtomValue(kioskModeAtom);
+ const isReading = mode === "read" || kioskMode;
const numColumns = useAtomValue(numColumnsAtom);
const isMultiColumn = numColumns > 1;
const [activeCellId, setActiveCellId] = useState<CellId | null>(null);
@@ -52,14 +56,23 @@ export const SlidesLayoutRenderer: React.FC<Props> = ({
activeIndex={resolvedIndex}
onSlideChange={handleSlideChange}
configWidth={300}
- mode={mode}
- isEditable={mode !== "read"}
+ mode={isReading ? "read" : mode}
+ isEditable={!isReading}
/>
);
if (isReading) {
- // Cap the deck height and derive width from height via aspect-video so it stays 16:9 without
- // ballooning to the full viewport on wide screens.
+ // In kiosk mode (e.g. reveal.js's speaker-view iframes), anchor to the
+ // iframe viewport with `dvh`/`dvw` so the deck resizes with the popup
+ // window. The non-kiosk read mode keeps its 16:9 cap so the deck doesn't
+ // balloon to the full viewport on wide screens.
+ if (kioskMode) {
+ return (
+ <div className="flex h-dvh w-dvw overflow-hidden bg-background">
+ {slides}
+ </div>
+ );
+ }
return (
<div className="p-4 flex flex-1 items-center justify-center min-h-0">
<div className="h-full max-h-[95vh] aspect-video max-w-full flex">
diff --git a/frontend/src/components/editor/renderers/slides-layout/types.ts b/frontend/src/components/editor/renderers/slides-layout/types.ts
index a87e7ded5a..eee62542d4 100644
--- a/frontend/src/components/editor/renderers/slides-layout/types.ts
+++ b/frontend/src/components/editor/renderers/slides-layout/types.ts
@@ -1,41 +1,50 @@
/* Copyright 2026 Marimo. All rights reserved. */
-/* oxlint-disable typescript/no-empty-object-type */
+import { z } from "zod";
import type { CellId } from "@/core/cells/ids";
+const SlideTypeSchema = z.enum(["slide", "sub-slide", "fragment", "skip"]);
+export type SlideType = z.infer<typeof SlideTypeSchema>;
+
+const SlideConfigSchema = z.looseObject({
+ type: SlideTypeSchema.optional(),
+ speakerNotes: z.string().optional(),
+});
+export type SlideConfig = z.infer<typeof SlideConfigSchema>;
+
+const DeckTransitionSchema = z.enum([
+ "none",
+ "fade",
+ "slide",
+ "convex",
+ "concave",
+ "zoom",
+]);
+export type DeckTransition = z.infer<typeof DeckTransitionSchema>;
+
+const DeckConfigSchema = z.looseObject({
+ transition: DeckTransitionSchema.optional(),
+});
+export type DeckConfig = z.infer<typeof DeckConfigSchema>;
+
/**
- * The serialized form of a slides layout.
- * This must be backwards-compatible as it is stored on the user's disk.
+ * Schema for the serialized form of a slides layout.
+ *
+ * This must be backwards-compatible as it is stored on the user's disk —
+ * fields are optional so files saved before they existed (e.g. the bare `{}`
+ * emitted by earlier marimo versions) still deserialize cleanly. Unknown
+ * keys are preserved (via `looseObject`) for the same reason.
*/
-// oxlint-disable-next-line typescript/consistent-type-definitions
-export type SerializedSlidesLayout = {
- // Both fields are optional so files saved before these existed (e.g. the
- // bare `{}` emitted by earlier marimo versions) still deserialize cleanly.
- deck?: DeckConfig;
- cells?: SlideConfig[];
-};
+export const SlidesLayoutSchema = z.looseObject({
+ cells: z.array(SlideConfigSchema).optional(),
+ deck: DeckConfigSchema.optional(),
+});
+export type SerializedSlidesLayout = z.infer<typeof SlidesLayoutSchema>;
-export interface SlidesLayout extends Omit<
- SerializedSlidesLayout,
- "cells" | "deck"
-> {
- // We map the cells to their IDs so that we can track them as they move around.
+/**
+ * Runtime form of a slides layout.
+ */
+export interface SlidesLayout {
cells: Map<CellId, SlideConfig>;
deck: DeckConfig;
}
-
-export type SlideType = "slide" | "sub-slide" | "fragment" | "skip";
-export interface SlideConfig {
- type?: SlideType;
-}
-
-export type DeckTransition =
- | "none"
- | "fade"
- | "slide"
- | "convex"
- | "concave"
- | "zoom";
-export interface DeckConfig {
- transition?: DeckTransition;
-}
diff --git a/frontend/src/components/slides/__tests__/slide-notes.test.ts b/frontend/src/components/slides/__tests__/slide-notes.test.ts
new file mode 100644
index 0000000000..5cc2692b61
--- /dev/null
+++ b/frontend/src/components/slides/__tests__/slide-notes.test.ts
@@ -0,0 +1,131 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import type {
+ SlideConfig,
+ SlideType,
+} from "@/components/editor/renderers/slides-layout/types";
+import type { CellId } from "@/core/cells/ids";
+import { cellId } from "@/__tests__/branded";
+import { composeSlides } from "../compose-slides";
+import { buildSubslideNotes, collectBlockNotes } from "../slide-notes";
+
+interface Cell {
+ id: CellId;
+ type?: SlideType;
+}
+
+const cell = (id: string, type?: SlideType): Cell => ({
+ id: cellId(id),
+ type,
+});
+
+const configs = (
+ notes: Record<string, string>,
+): ReadonlyMap<CellId, SlideConfig> =>
+ new Map(
+ Object.entries(notes).map(([id, speakerNotes]) => [
+ cellId(id),
+ { speakerNotes } satisfies SlideConfig,
+ ]),
+ );
+
+const firstSubslide = (cells: Cell[]) =>
+ composeSlides({ cells, getType: (c) => c.type ?? "slide" }).stacks[0]
+ .subslides[0];
+
+describe("collectBlockNotes", () => {
+ it("concatenates non-empty notes with paragraph spacing", () => {
+ const result = collectBlockNotes(
+ [cell("a"), cell("b"), cell("c")],
+ configs({ a: "first", b: "", c: "third" }),
+ );
+ expect(result).toBe("first\n\nthird");
+ });
+
+ it("returns an empty string when no cell has notes", () => {
+ expect(collectBlockNotes([cell("a")], configs({}))).toBe("");
+ });
+
+ it("ignores whitespace-only notes", () => {
+ expect(
+ collectBlockNotes([cell("a"), cell("b")], configs({ a: " ", b: "x" })),
+ ).toBe("x");
+ });
+});
+
+describe("buildSubslideNotes", () => {
+ it("returns empty notes when no cell has any", () => {
+ const subslide = firstSubslide([cell("a"), cell("b", "fragment")]);
+ expect(buildSubslideNotes(subslide, configs({}))).toEqual({
+ slideLevel: "",
+ cumulativeByBlock: new Map(),
+ });
+ });
+
+ it("returns only slide-level notes when there are no fragments", () => {
+ const subslide = firstSubslide([cell("a")]);
+ expect(buildSubslideNotes(subslide, configs({ a: "intro" }))).toEqual({
+ slideLevel: "intro",
+ cumulativeByBlock: new Map(),
+ });
+ });
+
+ it("accumulates fragments below the slide-level notes with a divider", () => {
+ const subslide = firstSubslide([
+ cell("a"),
+ cell("b", "fragment"),
+ cell("c", "fragment"),
+ ]);
+ const { slideLevel, cumulativeByBlock } = buildSubslideNotes(
+ subslide,
+ configs({ a: "intro", b: "step one", c: "step two" }),
+ );
+ expect(slideLevel).toBe("intro");
+ expect(cumulativeByBlock.get(1)).toBe("intro\n\n---\n\nstep one");
+ expect(cumulativeByBlock.get(2)).toBe(
+ "intro\n\n---\n\nstep one\n\n---\n\nstep two",
+ );
+ });
+
+ it("accumulates fragments with no slide-level notes", () => {
+ const subslide = firstSubslide([
+ cell("a"),
+ cell("b", "fragment"),
+ cell("c", "fragment"),
+ ]);
+ const { slideLevel, cumulativeByBlock } = buildSubslideNotes(
+ subslide,
+ configs({ b: "first reveal", c: "second reveal" }),
+ );
+ expect(slideLevel).toBe("");
+ expect(cumulativeByBlock.get(1)).toBe("first reveal");
+ expect(cumulativeByBlock.get(2)).toBe(
+ "first reveal\n\n---\n\nsecond reveal",
+ );
+ });
+
+ it("skips empty fragments without leaving dangling dividers", () => {
+ const subslide = firstSubslide([
+ cell("a"),
+ cell("b", "fragment"),
+ cell("c", "fragment"),
+ ]);
+ const { cumulativeByBlock } = buildSubslideNotes(
+ subslide,
+ configs({ a: "intro", c: "third" }),
+ );
+ expect(cumulativeByBlock.get(1)).toBe("intro");
+ expect(cumulativeByBlock.get(2)).toBe("intro\n\n---\n\nthird");
+ });
+
+ it("returns no cumulative entries when fragments and slide have no notes", () => {
+ const subslide = firstSubslide([
+ cell("a"),
+ cell("b", "fragment"),
+ cell("c", "fragment"),
+ ]);
+ const { cumulativeByBlock } = buildSubslideNotes(subslide, configs({}));
+ expect(cumulativeByBlock.size).toBe(0);
+ });
+});
diff --git a/frontend/src/components/slides/reveal-component.tsx b/frontend/src/components/slides/reveal-component.tsx
index 9d6c5a3db9..d3abba1a45 100644
--- a/frontend/src/components/slides/reveal-component.tsx
+++ b/frontend/src/components/slides/reveal-component.tsx
@@ -11,9 +11,11 @@ import {
import useEvent from "react-use-event-hook";
import { CodeIcon, ExpandIcon, EyeOffIcon } from "lucide-react";
import { Deck, Fragment, Slide, Stack } from "@revealjs/react";
+import { Panel, PanelGroup, PanelResizeHandle } from "react-resizable-panels";
import { Slide as CellOutputSlide } from "@/components/slides/slide";
import { Button } from "@/components/ui/button";
import { Tooltip } from "@/components/ui/tooltip";
+import type { CellId } from "@/core/cells/ids";
import type { RuntimeCell } from "@/core/cells/types";
import type { RevealApi, RevealConfig } from "reveal.js";
import { useEventListener } from "@/hooks/useEventListener";
@@ -21,7 +23,10 @@ import { Events } from "@/utils/events";
import { Logger } from "@/utils/Logger";
import "./slides.css";
import "./reveal-slides.css";
-import type { SlidesLayout } from "../editor/renderers/slides-layout/types";
+import type {
+ SlideConfig,
+ SlidesLayout,
+} from "../editor/renderers/slides-layout/types";
import {
buildSlideIndices,
composeSlides,
@@ -39,10 +44,14 @@ import {
SlideCellReadOnlyView,
SlideCellView,
} from "@/components/slides/slide-cell-view";
+import { SlideNotesEditor } from "./slide-notes-editor";
+import { buildSubslideNotes, NOTES_DIVIDER } from "./slide-notes";
import { cn } from "@/utils/cn";
import { isIslands } from "@/core/islands/utils";
import { useNotebookCodeAvailable } from "@/core/meta/code-visibility";
-import type { AppMode } from "@/core/mode";
+import { type AppMode, kioskModeAtom } from "@/core/mode";
+import { useAtomValue } from "jotai";
+import RevealNotes from "reveal.js/plugin/notes";
const ASPECT_RATIO = 16 / 9;
@@ -124,56 +133,93 @@ function triggerResize(deck: RevealApi | null) {
}
}
+// The speaker view renders this via innerHTML with `white-space: normal`, so
+// we materialize `\n` as `<br>` and a lone `---` line as `<hr>`.
+const NotesAside = ({ text }: { text: string }) => {
+ const lines = text.split("\n");
+ return (
+ <aside className="notes">
+ {lines.map((line, idx) => {
+ const isLast = idx === lines.length - 1;
+ if (line === NOTES_DIVIDER) {
+ return <hr key={idx} />;
+ }
+ return (
+ <ReactFragment key={idx}>
+ {line}
+ {!isLast && <br />}
+ </ReactFragment>
+ );
+ })}
+ </aside>
+ );
+};
+
const SubslideView = ({
subslide,
showCode,
isEditable,
+ slideConfigs,
}: {
subslide: ComposedSubslide<RuntimeCell>;
showCode: boolean;
isEditable: boolean;
-}) => (
- <Slide>
- <div className="h-full w-full overflow-auto flex">
- <div
- className={
- showCode ? "mo-slide-content flex flex-col gap-3" : "mo-slide-content"
- }
- style={{
- margin: "auto 20px",
- }}
- >
- {subslide.blocks.map((block, i) => {
- const rendered = block.cells.map((cell) => {
- if (!showCode) {
+ slideConfigs: ReadonlyMap<CellId, SlideConfig>;
+}) => {
+ const { slideLevel, cumulativeByBlock } = buildSubslideNotes(
+ subslide,
+ slideConfigs,
+ );
+
+ return (
+ <Slide>
+ <div className="h-full w-full overflow-auto flex">
+ <div
+ className={
+ showCode
+ ? "mo-slide-content flex flex-col gap-3"
+ : "mo-slide-content"
+ }
+ style={{
+ margin: "auto 20px",
+ }}
+ >
+ {subslide.blocks.map((block, i) => {
+ const rendered = block.cells.map((cell) => {
+ if (!showCode) {
+ return (
+ <CellOutputSlide
+ key={cell.id}
+ cellId={cell.id}
+ status={cell.status}
+ output={cell.output}
+ />
+ );
+ }
+ return isEditable ? (
+ <SlideCellView key={cell.id} cell={cell} />
+ ) : (
+ <SlideCellReadOnlyView key={cell.id} cell={cell} />
+ );
+ });
+ if (block.isFragment) {
+ const cumulative = cumulativeByBlock.get(i);
return (
- <CellOutputSlide
- key={cell.id}
- cellId={cell.id}
- status={cell.status}
- output={cell.output}
- />
+ <Fragment key={i} as="div">
+ {rendered}
+ {cumulative && <NotesAside text={cumulative} />}
+ </Fragment>
);
}
- return isEditable ? (
- <SlideCellView key={cell.id} cell={cell} />
- ) : (
- <SlideCellReadOnlyView key={cell.id} cell={cell} />
- );
- });
- if (block.isFragment) {
- return (
- <Fragment key={i} as="div">
- {rendered}
- </Fragment>
- );
- }
- return <ReactFragment key={i}>{rendered}</ReactFragment>;
- })}
+ return <ReactFragment key={i}>{rendered}</ReactFragment>;
+ })}
+ </div>
</div>
- </div>
- </Slide>
-);
+ {/* Outside any `.fragment`: shown only before any fragment is revealed. */}
+ {slideLevel && <NotesAside text={slideLevel} />}
+ </Slide>
+ );
+};
// There is an upstream react bug in dev mode (https://github.com/facebook/react/issues/34840)
// Uncaught SecurityError: Failed to read a named property '$$typeof' from 'Window'
@@ -200,6 +246,13 @@ const RevealSlidesComponent = ({
const containerRef = useRef<HTMLDivElement>(null);
const deckRef = useRef<RevealApi | null>(null);
const { width, height } = useSlideDimensions(containerRef);
+ // Skip the Notes plugin inside reveal's own speaker-view iframes so pressing
+ // `S` there doesn't try to spawn another popup.
+ const kioskMode = useAtomValue(kioskModeAtom);
+ const deckPlugins = useMemo(
+ () => (kioskMode ? [] : [RevealNotes]),
+ [kioskMode],
+ );
const [showCode, setShowCode] = useState(false);
const codeAvailable = useNotebookCodeAvailable(cellsWithOutput);
@@ -241,6 +294,16 @@ const RevealSlidesComponent = ({
);
const deckTransition = layout.deck?.transition ?? DEFAULT_DECK_TRANSITION;
+ // Reveal's Notes plugin iframes the deck for the current/upcoming-slide
+ // previews. We load the same URL but as a read-only kiosk client with the
+ // app chrome hidden, which `<SlidesLayoutRenderer>` interprets the same as
+ // read mode (no minimap, sidebar, or notes editor).
+ const kioskUrl = useMemo(() => {
+ const url = new URL(window.location.href);
+ url.searchParams.set("kiosk", "true");
+ url.searchParams.set("show-chrome", "false");
+ return url.toString();
+ }, []);
const revealConfig: RevealConfig = useMemo(
() => ({
embedded: true,
@@ -251,8 +314,9 @@ const RevealSlidesComponent = ({
maxScale: 2,
transition: deckTransition,
keyboardCondition: (event: KeyboardEvent) => !Events.fromInput(event),
+ url: kioskUrl,
}),
- [width, height, deckTransition],
+ [width, height, deckTransition, kioskUrl],
);
const navigateDeckToActiveCell = useEvent((deck: RevealApi) => {
@@ -357,126 +421,157 @@ const RevealSlidesComponent = ({
useEventListener(document, "keydown", handleParkedNavKey, { capture: true });
- return (
- <div className="flex-1 min-w-0 flex flex-row gap-3">
- <div
- ref={containerRef}
- className="flex-1 min-w-0 flex items-center justify-center overflow-hidden"
- >
- <div className="group relative" style={{ width, height }}>
- <Deck
- deckRef={deckRef}
- className="aspect-video w-full overflow-hidden border rounded bg-background mo-slides-theme prose-slides"
- config={revealConfig}
- onReady={handleDeckReady}
- onSlideChange={handleSlideChange}
- onFragmentShown={reportCurrentCell}
- onFragmentHidden={reportCurrentCell}
- >
- {composition.stacks.map((stack, h) => {
- if (stack.subslides.length === 1) {
- const isActive =
- activeSubslide?.h === h && activeSubslide?.v === 0;
- return (
- <SubslideView
- key={h}
- subslide={stack.subslides[0]}
- showCode={codeShown && isActive}
- isEditable={isEditable}
- />
- );
- }
+ const slideArea = (
+ <div
+ ref={containerRef}
+ className="h-full w-full min-w-0 flex items-center justify-center overflow-hidden"
+ >
+ <div className="group relative" style={{ width, height }}>
+ <Deck
+ deckRef={deckRef}
+ className="aspect-video w-full overflow-hidden border rounded bg-background mo-slides-theme prose-slides"
+ config={revealConfig}
+ onReady={handleDeckReady}
+ onSlideChange={handleSlideChange}
+ onFragmentShown={reportCurrentCell}
+ onFragmentHidden={reportCurrentCell}
+ plugins={deckPlugins}
+ >
+ {composition.stacks.map((stack, h) => {
+ if (stack.subslides.length === 1) {
+ const isActive =
+ activeSubslide?.h === h && activeSubslide?.v === 0;
return (
- <Stack key={h}>
- {stack.subslides.map((sub, v) => {
- const isActive =
- activeSubslide?.h === h && activeSubslide?.v === v;
- return (
- <SubslideView
- key={v}
- subslide={sub}
- showCode={codeShown && isActive}
- isEditable={isEditable}
- />
- );
- })}
- </Stack>
+ <SubslideView
+ key={h}
+ subslide={stack.subslides[0]}
+ showCode={codeShown && isActive}
+ isEditable={isEditable}
+ slideConfigs={layout.cells}
+ />
);
- })}
- </Deck>
- {skippedPreviewCell && (
- <div
- className="absolute inset-0 z-10 border rounded bg-background flex flex-col overflow-hidden"
- aria-label="Skipped in presentation"
- >
- <div className="flex items-center gap-1.5 px-3 py-1.5 text-xs text-muted-foreground border-b bg-muted/40">
- <EyeOffIcon className="h-3.5 w-3.5" />
- <span>Skipped in presentation</span>
- </div>
- <div className="flex-1 overflow-auto flex">
- <div
- className="mo-slide-content"
- style={{ margin: "auto 20px" }}
- >
- <CellOutputSlide
- cellId={skippedPreviewCell.id}
- status={skippedPreviewCell.status}
- output={skippedPreviewCell.output}
- />
- </div>
+ }
+ return (
+ <Stack key={h}>
+ {stack.subslides.map((sub, v) => {
+ const isActive =
+ activeSubslide?.h === h && activeSubslide?.v === v;
+ return (
+ <SubslideView
+ key={v}
+ subslide={sub}
+ showCode={codeShown && isActive}
+ isEditable={isEditable}
+ slideConfigs={layout.cells}
+ />
+ );
+ })}
+ </Stack>
+ );
+ })}
+ </Deck>
+ {skippedPreviewCell && (
+ <div
+ className="absolute inset-0 z-10 border rounded bg-background flex flex-col overflow-hidden"
+ aria-label="Skipped in presentation"
+ >
+ <div className="flex items-center gap-1.5 px-3 py-1.5 text-xs text-muted-foreground border-b bg-muted/40">
+ <EyeOffIcon className="h-3.5 w-3.5" />
+ <span>Skipped in presentation</span>
+ </div>
+ <div className="flex-1 overflow-auto flex">
+ <div className="mo-slide-content" style={{ margin: "auto 20px" }}>
+ <CellOutputSlide
+ cellId={skippedPreviewCell.id}
+ status={skippedPreviewCell.status}
+ output={skippedPreviewCell.output}
+ />
</div>
</div>
- )}
- <div className="absolute top-2 right-2 z-20 opacity-0 group-hover:opacity-70 text-muted-foreground transition-opacity">
- {codeToggleEnabled && (
- <Tooltip content={codeShown ? "Hide code (C)" : "Show code (C)"}>
- <Button
- data-testid="marimo-plugin-slides-toggle-code"
- variant="ghost"
- size="icon"
- className={cn(
- "text-muted-foreground h-7 w-7",
- codeShown && "text-foreground bg-muted",
- )}
- aria-pressed={codeShown}
- aria-label={codeShown ? "Hide code" : "Show code"}
- onClick={toggleShowCode}
- >
- <CodeIcon className="h-4 w-4" />
- </Button>
- </Tooltip>
- )}
- <Tooltip content="Fullscreen (F)">
+ </div>
+ )}
+ <div className="absolute top-2 right-2 z-20 opacity-0 group-hover:opacity-70 text-muted-foreground transition-opacity">
+ {codeToggleEnabled && (
+ <Tooltip content={codeShown ? "Hide code (C)" : "Show code (C)"}>
<Button
- data-testid="marimo-plugin-slides-fullscreen"
+ data-testid="marimo-plugin-slides-toggle-code"
variant="ghost"
size="icon"
- className="text-muted-foreground h-7 w-7"
- aria-label="Enter fullscreen"
- onClick={() => {
- deckRef.current
- ?.getViewportElement()
- ?.requestFullscreen()
- .catch((error) => {
- Logger.error("Failed to request fullscreen", error);
- });
- }}
+ className={cn(
+ "text-muted-foreground h-7 w-7",
+ codeShown && "text-foreground bg-muted",
+ )}
+ aria-pressed={codeShown}
+ aria-label={codeShown ? "Hide code" : "Show code"}
+ onClick={toggleShowCode}
>
- <ExpandIcon className="h-4 w-4" />
+ <CodeIcon className="h-4 w-4" />
</Button>
</Tooltip>
- </div>
+ )}
+ <Tooltip content="Fullscreen (F)">
+ <Button
+ data-testid="marimo-plugin-slides-fullscreen"
+ variant="ghost"
+ size="icon"
+ className="text-muted-foreground h-7 w-7"
+ aria-label="Enter fullscreen"
+ onClick={() => {
+ deckRef.current
+ ?.getViewportElement()
+ ?.requestFullscreen()
+ .catch((error) => {
+ Logger.error("Failed to request fullscreen", error);
+ });
+ }}
+ >
+ <ExpandIcon className="h-4 w-4" />
+ </Button>
+ </Tooltip>
</div>
</div>
+ </div>
+ );
+
+ if (mode === "read") {
+ return (
+ <div className="flex-1 min-w-0 flex flex-row gap-3">{slideArea}</div>
+ );
+ }
- {mode !== "read" && (
- <SlideSidebar
- configWidth={configWidth}
- layout={layout}
- setLayout={setLayout}
- activeConfigCell={activeConfigCell}
+ return (
+ <div className="flex-1 min-w-0 flex flex-row gap-3">
+ <PanelGroup
+ direction="vertical"
+ autoSaveId="marimo:slides:notes-panel"
+ className="flex-1 min-w-0"
+ >
+ <Panel defaultSize={92} minSize={60}>
+ {slideArea}
+ </Panel>
+ <PanelResizeHandle
+ className="mo-slides-notes-resize"
+ hitAreaMargins={{ coarse: 12, fine: 4 }}
/>
- )}
+ <Panel
+ defaultSize={10}
+ minSize={4}
+ collapsible={true}
+ collapsedSize={4}
+ >
+ <SlideNotesEditor
+ layout={layout}
+ setLayout={setLayout}
+ cellId={activeConfigCell?.id}
+ />
+ </Panel>
+ </PanelGroup>
+ <SlideSidebar
+ configWidth={configWidth}
+ layout={layout}
+ setLayout={setLayout}
+ activeConfigCell={activeConfigCell}
+ />
</div>
);
};
diff --git a/frontend/src/components/slides/slide-notes-editor.tsx b/frontend/src/components/slides/slide-notes-editor.tsx
new file mode 100644
index 0000000000..42e8a872f4
--- /dev/null
+++ b/frontend/src/components/slides/slide-notes-editor.tsx
@@ -0,0 +1,127 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { StickyNoteIcon } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import useEvent from "react-use-event-hook";
+import type { CellId } from "@/core/cells/ids";
+import { useDebouncedCallback } from "@/hooks/useDebounce";
+import { cn } from "@/utils/cn";
+import { Events } from "@/utils/events";
+import type { SlidesLayout } from "../editor/renderers/slides-layout/types";
+
+interface SlideNotesEditorProps {
+ layout: SlidesLayout;
+ setLayout: (layout: SlidesLayout) => void;
+ cellId: CellId | undefined;
+ className?: string;
+}
+
+const PERSIST_DELAY_MS = 300;
+
+export const SlideNotesEditor = ({
+ layout,
+ setLayout,
+ cellId,
+ className,
+}: SlideNotesEditorProps) => {
+ const initialValue = cellId
+ ? (layout.cells.get(cellId)?.speakerNotes ?? "")
+ : "";
+
+ const [draft, setDraft] = useState(initialValue);
+
+ // Tracks whether the user has typed something that hasn't been persisted
+ // yet. Used to decide if the textarea is safe to overwrite from props.
+ const hasPendingEditRef = useRef(false);
+
+ // The debounced callback takes `(cellId, text)` so a `flush()` replays with
+ // the latest args — which means the in-flight text lands on the slide it
+ // was typed for, even if `cellId` has since changed.
+ const persistImmediate = useEvent((targetCellId: CellId, next: string) => {
+ hasPendingEditRef.current = false;
+ const existing = layout.cells.get(targetCellId);
+ if ((existing?.speakerNotes ?? "") === next) {
+ return;
+ }
+ const newCells = new Map(layout.cells);
+ newCells.set(targetCellId, { ...existing, speakerNotes: next });
+ setLayout({ ...layout, cells: newCells });
+ });
+
+ const persistDebounced = useDebouncedCallback(
+ persistImmediate,
+ PERSIST_DELAY_MS,
+ );
+
+ // Keep the textarea in sync with `layout`:
+ // - On slide switch, flush any in-flight edit to the *previous* slide before
+ // adopting the new slide's notes.
+ // - On same-slide updates (e.g. future undo/redo or external setLayout
+ // writers), adopt the new value only when the user isn't mid-edit so
+ // pending keystrokes aren't clobbered.
+ const prevCellIdRef = useRef(cellId);
+ useEffect(() => {
+ if (prevCellIdRef.current !== cellId) {
+ persistDebounced.flush();
+ hasPendingEditRef.current = false;
+ setDraft(initialValue);
+ prevCellIdRef.current = cellId;
+ return;
+ }
+ if (!hasPendingEditRef.current && initialValue !== draft) {
+ setDraft(initialValue);
+ }
+ }, [cellId, initialValue, draft, persistDebounced]);
+
+ // Flush on unmount so closing the panel / navigating away doesn't lose text.
+ useEffect(() => {
+ return () => {
+ persistDebounced.flush();
+ };
+ }, [persistDebounced]);
+
+ const handleChange = (next: string) => {
+ setDraft(next);
+ if (cellId) {
+ hasPendingEditRef.current = true;
+ persistDebounced(cellId, next);
+ }
+ };
+
+ return (
+ <section
+ className={cn(
+ "h-full min-h-0 flex flex-col bg-muted/40 dark:bg-muted/20 border-t",
+ className,
+ )}
+ aria-label="Speaker notes"
+ // Keep keystrokes inside the textarea from advancing the reveal.js deck.
+ onKeyDown={(e) => e.stopPropagation()}
+ >
+ <header className="flex items-center gap-1.5 px-3 h-8 shrink-0 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+ <StickyNoteIcon className="h-3.5 w-3.5" />
+ <span>Speaker notes</span>
+ </header>
+ <div className="flex-1 min-h-0 p-2">
+ {cellId ? (
+ <textarea
+ value={draft}
+ onChange={(event) => handleChange(event.target.value)}
+ onClick={Events.stopPropagation()}
+ placeholder="Add notes for this slide. Visible to you in speaker view (press S during presentation)."
+ className={cn(
+ "h-full w-full resize-none rounded-sm border border-input/25 bg-background",
+ "px-3 py-2 text-sm leading-relaxed text-foreground placeholder:text-muted-foreground",
+ "ring-offset-background focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring focus-visible:border-accent",
+ )}
+ aria-label="Speaker notes for the current slide"
+ />
+ ) : (
+ <div className="h-full flex items-center justify-center text-xs text-muted-foreground">
+ Select a slide to add notes.
+ </div>
+ )}
+ </div>
+ </section>
+ );
+};
diff --git a/frontend/src/components/slides/slide-notes.ts b/frontend/src/components/slides/slide-notes.ts
new file mode 100644
index 0000000000..d3c36e347b
--- /dev/null
+++ b/frontend/src/components/slides/slide-notes.ts
@@ -0,0 +1,64 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { CellId } from "@/core/cells/ids";
+import type { SlideConfig } from "../editor/renderers/slides-layout/types";
+import type { ComposedSubslide } from "./compose-slides";
+
+/** Lone-line marker between blocks; `<NotesAside>` renders this as `<hr>`. */
+export const NOTES_DIVIDER = "---";
+
+const BLOCK_JOIN = `\n\n${NOTES_DIVIDER}\n\n`;
+
+export const collectBlockNotes = <C extends { id: CellId }>(
+ cells: readonly C[],
+ slideConfigs: ReadonlyMap<CellId, SlideConfig>,
+): string =>
+ cells
+ .map((cell) => slideConfigs.get(cell.id)?.speakerNotes ?? "")
+ .filter((note) => note.trim().length > 0)
+ .join("\n\n");
+
+export interface SubslideNotes {
+ /** Notes shown when no fragment is current. */
+ slideLevel: string;
+ /** Cumulative notes for each fragment block, keyed by block index. */
+ cumulativeByBlock: Map<number, string>;
+}
+
+/**
+ * Per-fragment cumulative notes: slide-level notes plus each revealed
+ * fragment's notes, separated by a horizontal-rule line.
+ */
+export const buildSubslideNotes = <C extends { id: CellId }>(
+ subslide: ComposedSubslide<C>,
+ slideConfigs: ReadonlyMap<CellId, SlideConfig>,
+): SubslideNotes => {
+ const blockNotes = subslide.blocks.map((block) =>
+ collectBlockNotes(block.cells, slideConfigs),
+ );
+
+ const slideLevel = subslide.blocks
+ .map((block, i) => (block.isFragment ? "" : blockNotes[i]))
+ .filter((note) => note.length > 0)
+ .join("\n\n");
+
+ const cumulativeByBlock = new Map<number, string>();
+ const revealsSoFar: string[] = [];
+ subslide.blocks.forEach((block, i) => {
+ if (!block.isFragment) {
+ return;
+ }
+ const myNotes = blockNotes[i];
+ if (myNotes.length > 0) {
+ revealsSoFar.push(myNotes);
+ }
+ const accumulated = [slideLevel, ...revealsSoFar]
+ .filter((s) => s.length > 0)
+ .join(BLOCK_JOIN);
+ if (accumulated.length > 0) {
+ cumulativeByBlock.set(i, accumulated);
+ }
+ });
+
+ return { slideLevel, cumulativeByBlock };
+};
diff --git a/frontend/src/components/slides/slides.css b/frontend/src/components/slides/slides.css
index f2ed1add82..9007697414 100644
--- a/frontend/src/components/slides/slides.css
+++ b/frontend/src/components/slides/slides.css
@@ -31,6 +31,20 @@
}
}
+/* Resize handle for the notes panel below the deck. Self-contained so the
+ slides layout doesn't have to inherit styles from app-chrome.css. */
+.mo-slides-notes-resize {
+ height: 4px;
+ background-color: transparent;
+ transition: background-color 200ms linear;
+ outline: none;
+}
+
+.mo-slides-notes-resize:hover,
+.mo-slides-notes-resize[data-resize-handle-active] {
+ background-color: var(--slate-11);
+}
+
/* helpful for debugging */
/* .mo-slide-content {
background-color: red;
diff --git a/frontend/src/core/edit-app.tsx b/frontend/src/core/edit-app.tsx
index 716be3e607..901d16d0c4 100644
--- a/frontend/src/core/edit-app.tsx
+++ b/frontend/src/core/edit-app.tsx
@@ -157,7 +157,7 @@ export const EditApp: React.FC<AppProps> = ({
"sticky left-0",
)}
>
- {isEditing && (
+ {!hideControls && isEditing && (
<div className="flex items-center justify-center container">
<FilenameForm filename={filename} />
</div>
diff --git a/marimo/_smoke_tests/slides_examples/layouts/nested_slides.slides.json b/marimo/_smoke_tests/slides_examples/layouts/nested_slides.slides.json
index a85dc17544..fdda33cca6 100644
--- a/marimo/_smoke_tests/slides_examples/layouts/nested_slides.slides.json
+++ b/marimo/_smoke_tests/slides_examples/layouts/nested_slides.slides.json
@@ -6,25 +6,32 @@
"type": "skip"
},
{
- "type": "slide"
+ "type": "slide",
+ "speakerNotes": "We first introduce slides in marimo, and how awesome they are!"
},
{
- "type": "fragment"
+ "type": "fragment",
+ "speakerNotes": "Then, introduce fragments, which reveal line"
},
{
- "type": "fragment"
+ "type": "fragment",
+ "speakerNotes": "by line"
},
{
- "type": "slide"
+ "type": "slide",
+ "speakerNotes": "Here's another slide on the agenda."
},
{
- "type": "slide"
+ "type": "slide",
+ "speakerNotes": "Section A onboard :>"
},
{
- "type": "sub-slide"
+ "type": "sub-slide",
+ "speakerNotes": "These are sub-slides! They flow from a previous slide vertically."
},
{
- "type": "fragment"
+ "type": "fragment",
+ "speakerNotes": "Some long long\n\ntext\n\nabout \n\nthis \n\nslide.\n\nIt's\n\nactually\n\njust plain\n\n\ntext!"
},
{
"type": "fragment"
@@ -81,4 +88,4 @@
],
"deck": {}
}
-}
\ No newline at end of file
+}
diff --git a/marimo/_smoke_tests/slides_examples/nested_slides.py b/marimo/_smoke_tests/slides_examples/nested_slides.py
index c1d694c1ce..2983dd2f75 100644
--- a/marimo/_smoke_tests/slides_examples/nested_slides.py
+++ b/marimo/_smoke_tests/slides_examples/nested_slides.py
@@ -1,6 +1,6 @@
import marimo
-__generated_with = "0.23.3"
+__generated_with = "0.23.6"
app = marimo.App(
width="medium",
layout_file="layouts/nested_slides.slides.json",