- {cell.kind === CellKind.CODE ? (
+ {cell.kind === CellKind.CODE && isHtmlLanguageId(cell.languageId) ? (
+
+ ) : cell.kind === CellKind.CODE ? (
{cell.value}
diff --git a/app/test/browser/run-cuj-scenarios.ts b/app/test/browser/run-cuj-scenarios.ts
index 2952d68e..40d2233b 100644
--- a/app/test/browser/run-cuj-scenarios.ts
+++ b/app/test/browser/run-cuj-scenarios.ts
@@ -79,6 +79,7 @@ function fetchWithTimeout(
}
const SCENARIO_DRIVERS = [
+ join(SCRIPT_DIR, "test-scenario-html-cell.ts"),
join(SCRIPT_DIR, "test-scenario-hello-world.ts"),
join(SCRIPT_DIR, "test-scenario-open-shared-drive-link.ts"),
join(SCRIPT_DIR, "test-scenario-appkernel-javascript.ts"),
diff --git a/app/test/browser/test-scenario-html-cell.ts b/app/test/browser/test-scenario-html-cell.ts
new file mode 100644
index 00000000..f84cdaf9
--- /dev/null
+++ b/app/test/browser/test-scenario-html-cell.ts
@@ -0,0 +1,335 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const FRONTEND_URL = process.env.CUJ_FRONTEND_URL?.trim() || "http://localhost:5173";
+const SCENARIO_NOTEBOOK_NAME = "scenario-html-cell.runme.md";
+
+const CURRENT_FILE_DIR = dirname(fileURLToPath(import.meta.url));
+const SCRIPT_DIR =
+ CURRENT_FILE_DIR.endsWith("/.generated") || CURRENT_FILE_DIR.endsWith("\\.generated")
+ ? dirname(CURRENT_FILE_DIR)
+ : CURRENT_FILE_DIR;
+const OUTPUT_DIR = join(SCRIPT_DIR, "test-output");
+const MOVIE_PATH = join(OUTPUT_DIR, "scenario-html-cell-walkthrough.webm");
+const AGENT_BROWSER_SESSION = process.env.AGENT_BROWSER_SESSION?.trim() ?? "";
+const AGENT_BROWSER_PROFILE = process.env.AGENT_BROWSER_PROFILE?.trim() ?? "";
+const AGENT_BROWSER_HEADED = (process.env.AGENT_BROWSER_HEADED ?? "false")
+ .trim()
+ .toLowerCase() === "true";
+const AGENT_BROWSER_KEEP_OPEN = (process.env.AGENT_BROWSER_KEEP_OPEN ?? "false")
+ .trim()
+ .toLowerCase() === "true";
+
+let passCount = 0;
+let failCount = 0;
+let totalCount = 0;
+
+function run(command: string): { status: number; stdout: string; stderr: string } {
+ const effectiveCommand = withAgentBrowserOptions(command);
+ const timeoutMs = Number(process.env.CUJ_SCENARIO_CMD_TIMEOUT_MS ?? "20000");
+ const result = spawnSync(effectiveCommand, {
+ shell: true,
+ encoding: "utf-8",
+ timeout: timeoutMs,
+ killSignal: "SIGKILL",
+ });
+ const errorCode =
+ typeof result.error === "object" && result.error !== null && "code" in result.error
+ ? String((result.error as { code?: string }).code ?? "")
+ : "";
+ const timedOut = errorCode === "ETIMEDOUT";
+ const timeoutHint = timedOut
+ ? `\n[scenario-timeout] command timed out after ${timeoutMs}ms: ${effectiveCommand}\n`
+ : "";
+ if (timedOut && effectiveCommand.trim().startsWith("agent-browser ")) {
+ throw new Error(timeoutHint.trim());
+ }
+ return {
+ status: result.status ?? (timedOut ? 124 : 1),
+ stdout: result.stdout ?? "",
+ stderr: `${result.stderr ?? ""}${timeoutHint}`,
+ };
+}
+
+function shellQuote(value: string): string {
+ return `'${value.replace(/'/g, `'\"'\"'`)}'`;
+}
+
+function withAgentBrowserOptions(command: string): string {
+ const trimmed = command.trimStart();
+ if (!trimmed.startsWith("agent-browser ")) {
+ return command;
+ }
+ const leadingWhitespace = command.slice(0, command.length - trimmed.length);
+ const subcommand = trimmed.slice("agent-browser ".length);
+ const args: string[] = [];
+ if (AGENT_BROWSER_SESSION) {
+ args.push("--session", shellQuote(AGENT_BROWSER_SESSION));
+ }
+ if (AGENT_BROWSER_PROFILE) {
+ args.push("--profile", shellQuote(AGENT_BROWSER_PROFILE));
+ }
+ if (AGENT_BROWSER_HEADED) {
+ args.push("--headed");
+ }
+ const prefix = ["agent-browser", ...args].join(" ");
+ return `${leadingWhitespace}${prefix} ${subcommand}`;
+}
+
+function escapeDoubleQuotes(value: string): string {
+ return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function pass(message: string): void {
+ totalCount += 1;
+ passCount += 1;
+ console.log(`[PASS] ${message}`);
+}
+
+function fail(message: string): void {
+ totalCount += 1;
+ failCount += 1;
+ console.log(`[FAIL] ${message}`);
+}
+
+function writeArtifact(name: string, content: string): void {
+ writeFileSync(join(OUTPUT_DIR, name), content, "utf-8");
+}
+
+function runWithRetry(command: string, attempts = 3, waitMs = 1200): void {
+ let lastError = "";
+ for (let attempt = 0; attempt < attempts; attempt += 1) {
+ const result = run(command);
+ if (result.status === 0) {
+ return;
+ }
+ lastError = result.stderr || result.stdout || `exit ${result.status}`;
+ if (attempt < attempts - 1) {
+ run(`agent-browser wait ${waitMs}`);
+ }
+ }
+ throw new Error(`Command failed after ${attempts} attempts: ${command}\n${lastError}`);
+}
+
+mkdirSync(OUTPUT_DIR, { recursive: true });
+rmSync(join(OUTPUT_DIR, "scenario-html-cell-01-initial.txt"), { force: true });
+rmSync(join(OUTPUT_DIR, "scenario-html-cell-02-opened.txt"), { force: true });
+rmSync(join(OUTPUT_DIR, "scenario-html-cell-03-preview.txt"), { force: true });
+rmSync(join(OUTPUT_DIR, "scenario-html-cell-03-preview.png"), { force: true });
+rmSync(MOVIE_PATH, { force: true });
+
+if (run("command -v agent-browser").status !== 0) {
+ console.error("ERROR: agent-browser is required on PATH");
+ process.exit(2);
+}
+
+if (run(`curl -sf ${FRONTEND_URL}`).status !== 0) {
+ console.error(`ERROR: frontend is not running at ${FRONTEND_URL}`);
+ process.exit(1);
+}
+
+runWithRetry(`agent-browser open ${FRONTEND_URL}`);
+runWithRetry(`agent-browser record restart ${MOVIE_PATH}`);
+run("agent-browser wait 2500");
+
+const seedResult = run(
+ `agent-browser eval "(async () => {
+ const ln = window.app?.localNotebooks;
+ if (!ln) return 'missing-local-notebooks';
+ const notebook = {
+ metadata: {},
+ cells: [
+ {
+ refId: 'cell_html_author',
+ kind: 2,
+ languageId: 'markdown',
+ value: '',
+ metadata: {},
+ outputs: []
+ }
+ ]
+ };
+ await ln.files.put({
+ id: 'local://file/${SCENARIO_NOTEBOOK_NAME}',
+ uri: 'local://file/${SCENARIO_NOTEBOOK_NAME}',
+ name: '${SCENARIO_NOTEBOOK_NAME}',
+ doc: JSON.stringify(notebook),
+ updatedAt: new Date().toISOString(),
+ parent: 'local://folder/local',
+ lastSynced: '',
+ remoteId: '',
+ lastRemoteChecksum: ''
+ });
+ localStorage.setItem('runme/openNotebooks', JSON.stringify([
+ { uri: 'local://file/${SCENARIO_NOTEBOOK_NAME}', name: '${SCENARIO_NOTEBOOK_NAME}', type: 'file', children: [] }
+ ]));
+ localStorage.setItem('runme/currentDoc', 'local://file/${SCENARIO_NOTEBOOK_NAME}');
+ return 'ok';
+ })()"`,
+).stdout;
+
+if (seedResult.includes("ok")) {
+ pass("Created local notebook fixture for HTML cell scenario");
+} else {
+ fail("Failed to create local notebook fixture for HTML cell scenario");
+}
+
+run("agent-browser reload");
+run("agent-browser wait 2200");
+
+let snapshot = run("agent-browser snapshot -i").stdout;
+writeArtifact("scenario-html-cell-01-initial.txt", snapshot);
+
+const notebookProbe = run(
+ `agent-browser eval "(async () => {
+ return document.getElementById('language-select-cell_html_author') ? 'ok' : 'missing-language-select';
+ })()"`,
+);
+const notebookProbeText = `${notebookProbe.stdout}\n${notebookProbe.stderr}`.trim();
+if (notebookProbe.status === 0 && notebookProbeText.includes("ok")) {
+ pass("Opened notebook with editable markdown cell");
+} else {
+ fail("Did not find editable markdown cell for HTML scenario");
+}
+
+const htmlSource = [
+ "
",
+ " ",
+ "
",
+].join("\n");
+
+const htmlSelectRaw = run(
+ `agent-browser eval "${escapeDoubleQuotes(`(() => {
+ const select = document.getElementById('language-select-cell_html_author');
+ if (!(select instanceof HTMLSelectElement)) {
+ return JSON.stringify({ status: 'missing-language-select' });
+ }
+ select.value = 'html';
+ select.dispatchEvent(new Event('change', { bubbles: true }));
+ const waitForHtmlEditor = () =>
+ new Promise((resolve) => {
+ const deadline = Date.now() + 5000;
+ const tick = () => {
+ const editor = document.getElementById('html-editor-cell_html_author');
+ if (editor || Date.now() > deadline) {
+ resolve(editor);
+ return;
+ }
+ setTimeout(tick, 50);
+ };
+ tick();
+ });
+ return waitForHtmlEditor().then((editor) =>
+ JSON.stringify({ status: editor ? 'ok' : 'missing-html-editor-container' })
+ );
+ })()`)}"`,
+);
+const htmlSelectText = `${htmlSelectRaw.stdout}\n${htmlSelectRaw.stderr}`.trim();
+writeArtifact("scenario-html-cell-02-opened.txt", htmlSelectText);
+
+let htmlEditorReady = false;
+try {
+ const parsedOnce = JSON.parse(htmlSelectRaw.stdout.trim()) as unknown;
+ const parsed = (typeof parsedOnce === "string"
+ ? JSON.parse(parsedOnce)
+ : parsedOnce) as { status?: string };
+ htmlEditorReady = parsed.status === "ok";
+} catch {
+ htmlEditorReady = false;
+}
+
+if (!htmlEditorReady) {
+ fail("HTML conversion/population did not complete: missing-html-editor-container");
+} else {
+ runWithRetry(
+ `agent-browser fill 'textarea[aria-label="Editor content"]' "${escapeDoubleQuotes(htmlSource)}"`,
+ );
+ run("agent-browser wait 600");
+}
+
+const convertAndPopulateRaw = run(
+ `agent-browser eval "${escapeDoubleQuotes(`(() => {
+ const editorContainer = document.getElementById('html-editor-cell_html_author');
+ if (!(editorContainer instanceof HTMLElement)) {
+ return JSON.stringify({ status: 'missing-html-editor-container', srcdoc: '', sandbox: '' });
+ }
+ editorContainer.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+ const deadline = Date.now() + 5000;
+ return new Promise((resolve) => {
+ const tick = () => {
+ const frame = document.querySelector('[data-testid="html-preview-frame"]');
+ const rendered = document.querySelector('[data-testid="html-rendered"]');
+ if ((frame && rendered) || Date.now() > deadline) {
+ resolve(JSON.stringify({
+ status: frame && rendered ? 'ok' : 'missing-preview',
+ srcdoc: frame instanceof HTMLIFrameElement ? frame.getAttribute('srcdoc') || '' : '',
+ sandbox: frame instanceof HTMLIFrameElement ? frame.getAttribute('sandbox') || '' : '',
+ }));
+ return;
+ }
+ setTimeout(tick, 50);
+ };
+ tick();
+ });
+ })()`)}"`,
+);
+const convertAndPopulateText = `${convertAndPopulateRaw.stdout}\n${convertAndPopulateRaw.stderr}`.trim();
+writeArtifact("scenario-html-cell-02-opened.txt", convertAndPopulateText);
+
+let previewSrcdoc = "";
+let previewSandbox = "";
+try {
+ const parsedOnce = JSON.parse(convertAndPopulateRaw.stdout.trim()) as unknown;
+ const parsed = (typeof parsedOnce === "string"
+ ? JSON.parse(parsedOnce)
+ : parsedOnce) as { status?: string; srcdoc?: string; sandbox?: string };
+ previewSrcdoc = parsed.srcdoc ?? "";
+ previewSandbox = parsed.sandbox ?? "";
+ if (parsed.status === "ok") {
+ pass("Converted markdown cell to HTML and populated inline SVG source");
+ } else {
+ fail(`HTML conversion/population did not complete: ${parsed.status ?? "unknown"}`);
+ }
+} catch {
+ fail("Could not parse HTML conversion result");
+}
+
+run("agent-browser wait 1200");
+run(`agent-browser screenshot ${join(OUTPUT_DIR, "scenario-html-cell-03-preview.png")}`);
+snapshot = run("agent-browser snapshot -i").stdout;
+writeArtifact("scenario-html-cell-03-preview.txt", snapshot);
+
+if (previewSrcdoc.includes("Hello SVG") && previewSrcdoc.includes("
0 ? 1 : 0);
diff --git a/app/vite.config.mts b/app/vite.config.mts
index b5c63c7b..c9c37ab0 100644
--- a/app/vite.config.mts
+++ b/app/vite.config.mts
@@ -12,6 +12,7 @@ const backendProxyTarget =
export default defineConfig({
// Use root-relative assets so LB rewrites to /index.html still load bundles from /.
base: "/",
+ cacheDir: ".vite",
publicDir: "assets",
optimizeDeps: {
exclude: ["@runmedev/renderers"],
diff --git a/app/vitest.config.mts b/app/vitest.config.mts
index f8646dfb..e7898fa9 100644
--- a/app/vitest.config.mts
+++ b/app/vitest.config.mts
@@ -3,6 +3,7 @@ import { resolve } from 'path'
import { defineConfig } from 'vitest/config'
export default defineConfig({
+ cacheDir: '.vite',
plugins: [react()],
test: {
environment: 'jsdom',
@@ -26,4 +27,4 @@ export default defineConfig({
'@': resolve(__dirname, './src'),
},
},
-})
\ No newline at end of file
+})
diff --git a/docs-dev/design/20260513_html_cells.md b/docs-dev/design/20260513_html_cells.md
new file mode 100644
index 00000000..1f376612
--- /dev/null
+++ b/docs-dev/design/20260513_html_cells.md
@@ -0,0 +1,355 @@
+# 2026-05-13: HTML Cells
+
+## Status
+
+Proposed and implemented in this branch.
+
+## Summary
+
+Add an `html` notebook cell mode that behaves like the existing markdown cell
+mode:
+
+- edit mode shows the raw HTML source in Monaco,
+- render mode previews the result in place,
+- the cell does not execute through a runner,
+- switching between source and preview is local UI behavior, not notebook
+ execution.
+
+We will represent HTML cells as existing `CODE` cells with
+`languageId: "html"`.
+
+We will not introduce a new protobuf `CellKind`.
+
+The rendered preview will use a sandboxed `iframe` with `srcDoc`, matching the
+existing trusted rendering path already used for `text/html` cell outputs, but
+with stricter script handling for authored cell content.
+
+## Motivation
+
+Today a user can render HTML or SVG in a notebook only indirectly:
+
+- code cells can emit `text/html` or `image/svg+xml` output bundles,
+- markdown cells render prose in place, but raw HTML is intentionally disabled
+ in the editable notebook UI.
+
+That leaves a product gap for authored rich content:
+
+- users cannot paste HTML or inline SVG as notebook source and preview it
+ directly,
+- the only current workaround is a runnable cell that emits the markup as
+ output,
+- that is heavier than necessary when the content is static or illustrative.
+
+An explicit HTML cell addresses that gap without weakening markdown safety.
+
+## Goals
+
+- Let users author HTML directly in notebook cells.
+- Support inline SVG through HTML source such as ``.
+- Preserve the markdown cell trust model. Markdown remains sanitized and does
+ not render raw HTML in the main notebook editor.
+- Avoid schema changes to the notebook protobuf model.
+- Reuse the existing HTML preview trust boundary where possible.
+- Keep HTML cells visible in source form when notebooks are serialized to
+ Markdown sidecars.
+
+## Non-Goals
+
+- Executing HTML cells through Runme runners, Jupyter, or AppKernel.
+- Adding a general-purpose raw-HTML mode to markdown cells.
+- Adding a separate `svg` cell type.
+- Building a full HTML document editor with assets, dependency management, or a
+ live dev server.
+- Introducing cross-cell scripting or access from preview iframes back into the
+ app shell.
+
+## Current State
+
+The existing notebook UI has two relevant behaviors.
+
+Markdown cells:
+
+- use `CellKind.MARKUP` or `languageId=markdown`,
+- render in place with `react-markdown`,
+- explicitly disable raw HTML in the editable notebook experience.
+
+Code cells:
+
+- render Monaco source,
+- may show rich outputs below the source,
+- already render `text/html` outputs inside a sandboxed `iframe srcDoc`.
+
+The existing notebook data model also hard-codes markup cells to markdown.
+
+That means the cleanest way to add HTML authoring is not to repurpose
+`CellKind.MARKUP`, but to recognize `languageId=html` as a notebook-native
+non-executing authored-content mode.
+
+## Decision
+
+We are choosing Option B:
+
+1. Represent HTML cells as `CellKind.CODE` with `languageId: "html"`.
+2. Add a dedicated in-place `HtmlCell` component with edit/render behavior
+ parallel to `MarkdownCell`.
+3. Render the preview through a sandboxed `iframe srcDoc`.
+4. Treat HTML cells as non-runnable content cells in the notebook UI.
+5. Serialize HTML cells into Markdown sidecars as raw HTML, not fenced code.
+6. In the first version, do not allow scripts in authored HTML previews.
+7. Gate execution on both `kind` and `languageId`, so `languageId=html` is
+ skipped by notebook execution APIs.
+
+## Why Reuse `CODE` + `languageId=html`
+
+Reasons:
+
+- No protobuf/schema migration is required.
+- Existing notebook APIs and storage already preserve arbitrary code
+ `languageId` values.
+- Monaco already understands `html`.
+- Language switching can convert between `markdown`, `html`, and runnable code
+ languages without inventing a third structural cell kind.
+- It keeps the meaning explicit: markdown is markup prose, html is raw trusted
+ DOM content.
+
+We explicitly do not reuse `CellKind.MARKUP` for HTML, because that kind is
+already semantically and programmatically tied to markdown behavior across the
+app.
+
+## UX
+
+### Authoring
+
+HTML cells should feel like markdown cells:
+
+- empty HTML cells start in edit mode,
+- non-empty HTML cells start in rendered mode,
+- double-click rendered preview enters edit mode,
+- `Esc` or blur returns to preview when non-empty,
+- `Shift+Enter` or the editor's existing run gesture should preview rather than
+ execute.
+
+Edit mode uses Monaco with `language="html"`.
+
+### Language switching
+
+The language selector should add `HTML`.
+
+Conversions:
+
+- `markdown` -> `html`
+ - convert to `CellKind.CODE`
+ - set `languageId` to `html`
+- `html` -> runnable language
+ - keep `CellKind.CODE`
+ - change `languageId`
+ - clear runner/kernel metadata as needed
+- runnable language -> `html`
+ - keep `CellKind.CODE`
+ - set `languageId` to `html`
+ - clear runner/kernel metadata
+
+We keep `markdown` special because it still maps to `CellKind.MARKUP`.
+
+### Empty notebook affordance
+
+The existing "add first cell" button currently creates a markdown cell.
+
+We will keep that behavior. HTML is an opt-in language choice, not the default
+for new notebooks.
+
+## Rendering and Security
+
+HTML preview is contained content, but it should not be treated as trusted by
+default.
+
+We will render the preview with:
+
+- `iframe`
+- `srcDoc={cell.value}`
+- `sandbox` with no `allow-scripts` token in the first version
+
+This is intentionally stricter than the current `text/html` output path.
+
+Rationale:
+
+- It isolates CSS and DOM from the notebook shell.
+- It lets inline SVG work naturally.
+- It avoids `dangerouslySetInnerHTML` in the main React tree.
+- It still supports the immediate HTML-cell use case of static HTML, CSS, and
+ inline SVG.
+- It avoids automatically executing JavaScript just by opening a notebook.
+
+This is intentionally different from markdown:
+
+- markdown remains a constrained authoring surface,
+- html is an explicit raw-content mode with a visibly different trust boundary.
+
+This proposal does not add `allow-same-origin` or message-passing from the
+preview back into the app.
+
+### Future trust model
+
+Longer term, we should add an explicit notebook trust model instead of treating
+all HTML cells the same.
+
+Recommended direction:
+
+- notebooks opened from local disk, Drive, or shared links start untrusted,
+- untrusted notebooks render HTML cells with scripts disabled,
+- users can explicitly mark a notebook trusted,
+- trusted notebooks may opt into richer preview capabilities, including script
+ execution, if product demand justifies it.
+
+The closest existing precedent is Jupyter's notebook trust model. JupyterLab's
+current user docs say that JavaScript and HTML from notebooks created on other
+machines are not trusted by default, that interactive outputs are blocked until
+the notebook is explicitly trusted, and that markdown cells are always
+sanitized. The classic Notebook security docs make the same distinction: for
+untrusted notebooks, HTML is sanitized, JavaScript is not executed, and users
+can explicitly trust a notebook later.
+
+Sources:
+
+- [JupyterLab user docs: Trust](https://jupyterlab.readthedocs.io/en/stable/user/notebook.html#trust)
+- [Jupyter Notebook security docs](https://jupyter-server.readthedocs.io/en/latest/operators/security.html)
+
+We do not need to build Jupyter's full signature-based trust model in the first
+HTML-cell iteration, but its policy shape is a useful reference:
+
+- safe default on open,
+- explicit upgrade to trusted,
+- no raw HTML/JS execution in markdown.
+
+## Notebook Serialization
+
+Markdown sidecars currently serialize:
+
+- markdown cells as prose,
+- code cells as fenced code blocks.
+
+HTML cells are authored content, not executable source, so fenced-code output is
+the wrong projection for search/readability.
+
+We will serialize HTML cells as raw HTML text with trailing whitespace trimmed,
+similar to how markdown cells are emitted directly.
+
+Consequences:
+
+- Drive sidecars remain readable.
+- Search can index text inside HTML and SVG source.
+- An exported sidecar keeps a faithful authored representation.
+
+We are not trying to sanitize or pretty-print the HTML during serialization.
+
+## Read-Only Notebook Views
+
+Any read-only notebook presentation that currently distinguishes only between
+code and markdown should also recognize `languageId=html`.
+
+For those views, HTML cells should render as authored content instead of showing
+only a code block.
+
+That keeps shared/opened notebooks consistent with the main editor experience.
+
+For the first version, read-only views should use the same no-scripts preview
+policy as the editable notebook view. Opening a shared notebook should not
+execute authored JavaScript automatically.
+
+## Execution Semantics
+
+HTML cells are stored as `CellKind.CODE` for compatibility, but they are not
+semantically runnable code cells.
+
+Short-term recommendation:
+
+- keep `CellKind.CODE` plus `languageId=html`,
+- treat `languageId=html` as a non-runnable subtype everywhere execution is
+ dispatched,
+- gate execution on both cell kind and normalized language, not cell kind
+ alone.
+
+That means at minimum:
+
+- the per-cell editor should not show run affordances for HTML cells,
+- `runme.runAll()` should skip HTML cells,
+- `notebooks.execute({ target, refIds })` should skip or reject HTML cells
+ explicitly,
+- any future bulk execution helper should follow the same rule.
+
+Why this is the right short-term tradeoff:
+
+- it avoids a schema migration,
+- it keeps language-switching simple,
+- it preserves the existing storage model,
+- it prevents accidental execution of raw markup through shell, Jupyter, or
+ AppKernel paths.
+
+If we later find that `kind=CODE` creates too much branching or ambiguity, we
+can revisit a dedicated protobuf kind. That should be a follow-on cleanup, not a
+prerequisite for the initial feature.
+
+## Testing
+
+Required coverage:
+
+1. Unit tests for notebook cell language switching.
+2. Unit tests for notebook serialization of HTML cells.
+3. UI tests for rendering/editing behavior where practical in JSDOM.
+4. Browser scenario validation that:
+ - creates or opens a notebook,
+ - switches a cell to HTML,
+ - enters HTML containing inline SVG,
+ - exits edit mode,
+ - verifies the preview renders expected text/SVG markers,
+ - records a `.webm` walkthrough.
+5. Execution-path tests proving that HTML cells are skipped by `runAll` and
+ rejected or ignored by `notebooks.execute(...)`.
+6. Trust-boundary tests proving that authored scripts do not run in HTML cell
+ previews in the first version.
+
+## Alternatives Considered
+
+### Option A: Enable raw HTML in markdown cells
+
+Rejected.
+
+Reasons:
+
+- It weakens the markdown safety model.
+- It mixes two trust levels into one cell type.
+- It makes it harder for users to understand whether a cell is prose or raw
+ DOM content.
+
+### Option B: New protobuf `CellKind.HTML`
+
+Rejected for now.
+
+Reasons:
+
+- Requires schema and compatibility work with little immediate benefit.
+- The existing `languageId` field already provides enough expressiveness.
+
+### Option C: SVG-only cells
+
+Rejected.
+
+Reasons:
+
+- HTML already covers inline SVG.
+- A separate SVG-only mode creates unnecessary surface area.
+
+## Rollout Notes
+
+This design is intentionally minimal.
+
+If we later find strong demand for richer embedded documents, we can extend the
+preview shell with:
+
+- default sizing helpers,
+- resize affordances,
+- safer preview metadata,
+- optional source formatting.
+
+Those are follow-on improvements, not prerequisites for the first HTML cell
+feature.
diff --git a/docs-dev/design/20260513_notebook_stdin_mocks.html b/docs-dev/design/20260513_notebook_stdin_mocks.html
new file mode 100644
index 00000000..27f8f2d7
--- /dev/null
+++ b/docs-dev/design/20260513_notebook_stdin_mocks.html
@@ -0,0 +1,491 @@
+
+
+
+
+
+ Notebook stdin UX mocks
+
+
+
+
+
+ Mock Study
+ Notebook stdin UX directions
+
+ These mocks compare what upstream Jupyter does today with a more explicit
+ notebook-native input flow for Runme. All three keep stdin inside the cell
+ output area. The difference is how obvious the waiting state is and whether
+ input feels like a terminal or a form submission.
+
+
+
+
+
+
+
+
+ Notebook 7 / JupyterLab
+ kernel: Python 3
+
+
+
In [12]:
+
+
name = input("Name: ")
+print(f"Hello {name}")
+
+
+
Name: Ada
+
Hello Ada
+
+
+
+
+
Why teams copy this
+
+ - It matches upstream behavior closely.
+ - It keeps input in the transcript instead of in a separate terminal.
+ - It works for ordinary `input()` prompts and debugger input.
+
+
+
+ Runme notebook
+ runner: bash
+
+
+
In [7]:
+
+
printf "Continue? [y/N] "
+read -r answer
+printf "\nanswer=%s\n" "$answer"
+
+
Continue? [y/N]
+
+
+ Waiting
+ Process is blocked on stdin.
+
+
+
+
+
+
+ One submit sends a single stdin write ending with a newline.
+
+
+
+
+
+
+
Why this is stronger for Runme
+
+ - The waiting state is explicit instead of implied by cursor focus.
+ - It avoids terminal-style key-by-key UX inside notebook cells.
+ - It scales better to browser tests and automation.
+
+
+
+ Secret input
+ runner: shell
+
+
+
In [19]:
+
+
sudo something-that-prompts
+
+ stdin requested
+ echo disabled
+
+
+
Xcode Command Line Tools is already installed.
+Password:
+
+
+ Secure
+ Password input is masked and not echoed into output.
+
+
+
+
+
+
+ This needs an explicit backend signal. The UI should not guess.
+
+
+
+
+
+
+
Boundary
+
+ - This is only viable if the runtime tells us `password=true` or `echo=false`.
+ - Without that signal, notebook stdin should stay visible text only.
+ - If we need raw TTY behavior, it belongs in a real terminal surface.
+
+