From e9871ae4fcde9389be182cb25a5d118697c2ad86 Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Tue, 2 Sep 2025 17:44:29 -0700
Subject: [PATCH 01/16] add 3s debounce to file watcher

---
 cli/cli.ts | 28 +++++++++++++++++++++++-----
 1 file changed, 23 insertions(+), 5 deletions(-)

diff --git a/cli/cli.ts b/cli/cli.ts
index 180a1dc32090..b8fbab2998cf 100644
--- a/cli/cli.ts
+++ b/cli/cli.ts
@@ -2811,6 +2811,9 @@ function pxtVersion(): string {
 
 function buildAndWatchAsync(f: () => Promise<string[]>, maxDepth: number): Promise<void> {
     let currMtime = Date.now()
+    const DEBOUNCE_MS = 3000;
+    let debounceTimer: any = null;
+
     return f()
         .then(dirs => {
             if (globalConfig.noAutoBuild) return
@@ -2821,11 +2824,26 @@ function buildAndWatchAsync(f: () => Promise<string[]>, maxDepth: number): Promi
                     .then(num => {
                         if (num > currMtime) {
                             currMtime = num
-                            f()
-                                .then(d => {
-                                    dirs = d
-                                    U.nextTick(loop)
-                                })
+                            if (debounceTimer) {
+                                clearTimeout(debounceTimer)
+                                debounceTimer = null
+                            }
+
+                            debounceTimer = setTimeout(() => {
+                                debounceTimer = null
+                                f()
+                                    .then(d => {
+                                        dirs = d
+                                        U.nextTick(loop)
+                                    })
+                                    .catch((e) => {
+                                        buildFailed("debounced build failed: " + (e && e.message ? e.message : ""), e)
+                                        U.nextTick(loop)
+                                    })
+                            }, DEBOUNCE_MS)
+
+                            // continue polling so subsequent changes reset debounceTimer
+                            U.nextTick(loop)
                         } else {
                             U.nextTick(loop)
                         }

From 5bdb8ab30e295d7ac2b4c154be47c729150dc710 Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Tue, 2 Sep 2025 17:45:15 -0700
Subject: [PATCH 02/16] chat component init

---
 .../components/controls/Chat/Chat.test.tsx    |  97 ++++++++++++
 .../components/controls/Chat/Chat.tsx         |  43 +++++
 .../components/controls/Chat/ChatComposer.tsx |  81 ++++++++++
 .../controls/Chat/ChatMessageList.tsx         | 149 ++++++++++++++++++
 .../components/controls/Chat/README.md        |  59 +++++++
 .../controls/Chat/chat.registry.tsx           |  97 ++++++++++++
 .../controls/Chat/chat.serialization.ts       |  49 ++++++
 .../components/controls/Chat/chat.stories.tsx | 115 ++++++++++++++
 .../components/controls/Chat/chat.types.ts    |  67 ++++++++
 react-common/styles/controls/Chat.less        | 122 ++++++++++++++
 react-common/styles/react-common.less         |   1 +
 svgicons/chat.svg                             |   1 +
 12 files changed, 881 insertions(+)
 create mode 100644 react-common/components/controls/Chat/Chat.test.tsx
 create mode 100644 react-common/components/controls/Chat/Chat.tsx
 create mode 100644 react-common/components/controls/Chat/ChatComposer.tsx
 create mode 100644 react-common/components/controls/Chat/ChatMessageList.tsx
 create mode 100644 react-common/components/controls/Chat/README.md
 create mode 100644 react-common/components/controls/Chat/chat.registry.tsx
 create mode 100644 react-common/components/controls/Chat/chat.serialization.ts
 create mode 100644 react-common/components/controls/Chat/chat.stories.tsx
 create mode 100644 react-common/components/controls/Chat/chat.types.ts
 create mode 100644 react-common/styles/controls/Chat.less
 create mode 100644 svgicons/chat.svg

diff --git a/react-common/components/controls/Chat/Chat.test.tsx b/react-common/components/controls/Chat/Chat.test.tsx
new file mode 100644
index 000000000000..f56895d221ce
--- /dev/null
+++ b/react-common/components/controls/Chat/Chat.test.tsx
@@ -0,0 +1,97 @@
+declare var test: any;
+declare var expect: any;
+declare var jest: any;
+declare var describe: any;
+
+import * as React from "react";
+import * as ReactDOM from "react-dom";
+import { act } from "react-dom/test-utils";
+import Chat from "./Chat";
+import ChatMessageList from "./ChatMessageList";
+import ChatComposer from "./ChatComposer";
+import { exportEnvelope, importEnvelope } from "./chat.serialization";
+import { Message } from "./chat.types";
+
+function query(selector: string) {
+    return document.querySelector(selector) as HTMLElement | null;
+}
+
+describe("Chat component basics", () => {
+    test("composer sends on Enter (no Shift)", () => {
+        let sent: string | null = null;
+        let root: HTMLDivElement | null = document.createElement("div");
+        document.body.appendChild(root);
+
+        act(() => {
+            ReactDOM.render(<ChatComposer onSend={(v) => (sent = v)} />, root);
+        });
+
+        const textarea = query(".common-chat-composer-textarea") as HTMLTextAreaElement | null;
+        if (!textarea) throw new Error("Textarea not found");
+
+        act(() => {
+            textarea.value = "hello world";
+            // fire input event to update any internal state (component uses onChange)
+            const inputEv = new Event("input", { bubbles: true });
+            textarea.dispatchEvent(inputEv);
+            const ev = new KeyboardEvent("keydown", { bubbles: true, cancelable: true, key: "Enter" });
+            textarea.dispatchEvent(ev);
+        });
+
+        if (sent !== "hello world") throw new Error(`expected sent 'hello world' got ${sent}`);
+
+        ReactDOM.unmountComponentAtNode(root);
+        root.remove();
+    });
+
+    test("windowing renders only tail window", () => {
+        const many: Message[] = [];
+        for (let i = 0; i < 100; ++i) {
+            many.push({ id: `m${i}`, author: i % 2 ? "user" : "assistant", timestamp: new Date().toISOString(), parts: [{ kind: "text", text: `message ${i}` }] });
+        }
+
+        let root: HTMLDivElement | null = document.createElement("div");
+        document.body.appendChild(root);
+        act(() => {
+            ReactDOM.render(<ChatMessageList messages={many} tailSize={10} overscan={4} />, root);
+        });
+
+        const rendered = (root.querySelectorAll(".common-chat-message") || []) as NodeListOf<Element>;
+        if (rendered.length !== 14) throw new Error(`expected 14, found ${rendered.length}`);
+
+        ReactDOM.unmountComponentAtNode(root);
+        root.remove();
+    });
+
+    test("registry custom card renders via Chat", () => {
+        const registry = {
+            testcard: {
+                render: (part: any) => React.createElement("div", { "data-testid": "testcard" }, part.title || "X"),
+            },
+        } as any;
+
+        const messages: Message[] = [{ id: "c1", author: "assistant", timestamp: new Date().toISOString(), parts: [{ kind: "testcard", title: "Hello" }] }];
+
+        let root: HTMLDivElement | null = document.createElement("div");
+        document.body.appendChild(root);
+        act(() => {
+            ReactDOM.render(<Chat messages={messages} onSend={() => {}} registry={registry} />, root);
+        });
+
+        const testcard = root.querySelector('[data-testid="testcard"]');
+        if (!testcard) throw new Error("testcard did not render");
+
+        ReactDOM.unmountComponentAtNode(root);
+        root.remove();
+    });
+
+    test("serialization roundtrip", () => {
+        const messages: Message[] = [{ id: "s1", author: "assistant", timestamp: new Date().toISOString(), parts: [{ kind: "text", text: "abc" }] }];
+        const envelope = exportEnvelope(messages);
+        const json = JSON.stringify(envelope);
+        const imported = importEnvelope(json);
+        if (imported.schemaVersion !== envelope.schemaVersion) throw new Error("schema mismatch");
+        if (!imported.messages || imported.messages.length !== 1) throw new Error("missing message after import");
+        if ((imported.messages[0].parts[0] as any).text !== "abc") throw new Error("text mismatch");
+    });
+});
diff --git a/react-common/components/controls/Chat/Chat.tsx b/react-common/components/controls/Chat/Chat.tsx
new file mode 100644
index 000000000000..7bd9a19a1088
--- /dev/null
+++ b/react-common/components/controls/Chat/Chat.tsx
@@ -0,0 +1,43 @@
+import * as React from "react";
+import { classList, ContainerProps } from "../../util";
+import ChatMessageList from "./ChatMessageList";
+import ChatComposer from "./ChatComposer";
+import { ChatRegistry, createRegistry } from "./chat.registry";
+import { Message } from "./chat.types";
+
+export interface ChatProps extends ContainerProps {
+    messages: Message[];
+    onSend: (messageOrText: Message | string) => void;
+    onAppend?: (message: Message) => void;
+    registry?: ChatRegistry;
+    uploadHandlers?: any;
+    tailSize?: number;
+    overscan?: number;
+    style?: React.CSSProperties;
+}
+
+export const Chat = (props: ChatProps) => {
+    const { id, className, style, messages, onSend, onAppend, registry, tailSize, overscan } = props;
+
+    const mergedRegistry = React.useMemo(() => createRegistry(registry), [registry]);
+
+    const handleSend = (text: string) => {
+        // top-level convenience: allow composer to call with text
+        const message: Message = {
+            id: `${Date.now()}`,
+            parts: [{ kind: "text", text }],
+            author: "user",
+            timestamp: new Date().toISOString(),
+        };
+        if (onSend) onSend(message);
+    };
+
+    return (
+        <div id={id} className={classList("common-chat", className)} style={style}>
+            <ChatMessageList messages={messages} registry={mergedRegistry} onAppend={onAppend} tailSize={tailSize} overscan={overscan} />
+            <ChatComposer onSend={handleSend} />
+        </div>
+    );
+};
+
+export default Chat;
diff --git a/react-common/components/controls/Chat/ChatComposer.tsx b/react-common/components/controls/Chat/ChatComposer.tsx
new file mode 100644
index 000000000000..b0ab5c6a2b0a
--- /dev/null
+++ b/react-common/components/controls/Chat/ChatComposer.tsx
@@ -0,0 +1,81 @@
+import * as React from "react";
+import { classList, ContainerProps } from "../../util";
+import { Button } from "../Button";
+
+export interface ChatComposerProps extends ContainerProps {
+    onSend: (value: string) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    busy?: boolean;
+    style?: React.CSSProperties;
+}
+
+export const ChatComposer = (props: ChatComposerProps) => {
+    const { onSend, className, style, placeholder, disabled, busy } = props;
+    const [value, setValue] = React.useState("");
+    const textareaRef = React.useRef<HTMLTextAreaElement | null>(null);
+
+    React.useEffect(() => {
+        // auto resize on mount
+        if (textareaRef.current) {
+            textareaRef.current.style.height = "1px";
+            textareaRef.current.style.height = `${textareaRef.current.scrollHeight}px`;
+        }
+    }, []);
+
+    const maybeResize = () => {
+        if (!textareaRef.current) return;
+        textareaRef.current.style.height = "1px";
+        textareaRef.current.style.height = `${textareaRef.current.scrollHeight}px`;
+    };
+
+    const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+        if (e.key === "Enter" && !e.shiftKey) {
+            // send
+            e.preventDefault();
+            const trimmed = value.trim();
+            if (!trimmed) return;
+            onSend(trimmed);
+            setValue("");
+        }
+    };
+
+    const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+        setValue(e.target.value);
+        maybeResize();
+    };
+
+    const doSend = () => {
+        const trimmed = value.trim();
+        if (!trimmed) return;
+        onSend(trimmed);
+        setValue("");
+        if (textareaRef.current) {
+            textareaRef.current.style.height = "1px";
+        }
+    };
+
+    return (
+        <div className={classList("common-chat-composer", className)} style={style}>
+            <textarea
+                ref={textareaRef}
+                className={classList("common-textarea", "common-chat-composer-textarea")}
+                placeholder={placeholder || lf("Type a message...")}
+                value={value}
+                onChange={handleChange}
+                onKeyDown={handleKeyDown}
+                aria-label={placeholder || lf("Message input")}
+                disabled={disabled}
+            />
+            <Button
+                className={classList("common-chat-send-button")}
+                title={lf("Send")}
+                label={busy ? <div className="common-spinner" /> : lf("Send")}
+                onClick={doSend}
+                disabled={disabled || busy || value.trim().length === 0}
+            />
+        </div>
+    );
+};
+
+export default ChatComposer;
diff --git a/react-common/components/controls/Chat/ChatMessageList.tsx b/react-common/components/controls/Chat/ChatMessageList.tsx
new file mode 100644
index 000000000000..cd6a2edd8c0b
--- /dev/null
+++ b/react-common/components/controls/Chat/ChatMessageList.tsx
@@ -0,0 +1,149 @@
+import * as React from "react";
+import { classList } from "../../util";
+import { Message, MessagePart } from "./chat.types";
+import { ChatRegistry, createRegistry, unknownKindRenderer, PartRenderContext } from "./chat.registry";
+
+export interface ChatMessageListProps {
+    id?: string;
+    className?: string;
+    style?: React.CSSProperties;
+
+    messages: Message[];
+    registry?: ChatRegistry;
+
+    // How many items from the tail to keep rendered (simple tail-biased windowing)
+    tailSize?: number; // default 75
+    overscan?: number; // default 12
+
+    onAppend?: (m: Message) => void;
+}
+
+export const ChatMessageList = (props: ChatMessageListProps) => {
+    const { id, className, style, messages, registry, tailSize = 75, overscan = 12, onAppend } = props;
+
+    const mergedRegistry = React.useMemo(() => createRegistry(registry), [registry]);
+
+    const containerRef = React.useRef<HTMLDivElement | null>(null);
+    const lastMessageRef = React.useRef<HTMLElement | null>(null);
+
+    // ephemeral UI state kept outside the transcript; keyed by message id
+    const [uiState, setUiState] = React.useState<{ [msgId: string]: any }>({});
+
+    const updateUiState = React.useCallback((msgId: string, slot: string, value: any) => {
+        setUiState((prev) => {
+            const next = { ...(prev || {}) };
+            const entry = { ...(next[msgId] || {}) };
+            entry[slot] = value;
+            next[msgId] = entry;
+            return next;
+        });
+    }, []);
+
+    const atBottomRef = React.useRef<boolean>(true);
+    const setAtBottom = (v: boolean) => {
+        atBottomRef.current = v;
+    };
+
+    // compute windowed indexes (simple tail-window strategy)
+    const startIndex = Math.max(0, messages.length - tailSize - overscan);
+    const visibleMessages = messages.slice(startIndex);
+
+    // IntersectionObserver to track whether the tail is in view.
+    React.useEffect(() => {
+        const observerRoot = containerRef.current;
+        if (!observerRoot) return () => {};
+
+        const observer = new IntersectionObserver(
+            (entries) => {
+                for (const e of entries) {
+                    // when last message is visible, consider we are at bottom
+                    if (e.target === lastMessageRef.current) {
+                        setAtBottom(e.isIntersecting);
+                    }
+                }
+            },
+            { root: observerRoot, threshold: 0.6 }
+        );
+
+        if (lastMessageRef.current) {
+            observer.observe(lastMessageRef.current);
+        }
+        return () => {
+            observer.disconnect();
+        };
+    }, [visibleMessages.length]);
+
+    // Keep previous messages length to detect append
+    const prevLen = React.useRef<number>(messages.length);
+    React.useEffect(() => {
+        if (messages.length > prevLen.current) {
+            // messages appended at the end
+            const appended = messages.slice(prevLen.current);
+            appended.forEach((m) => onAppend?.(m));
+
+            // if the user was at bottom, scroll to end
+            if (atBottomRef.current && containerRef.current) {
+                // use requestAnimationFrame to avoid layout thrash
+                requestAnimationFrame(() => {
+                    if (!containerRef.current) return;
+                    containerRef.current.scrollTop = containerRef.current.scrollHeight;
+                });
+            }
+        }
+        prevLen.current = messages.length;
+    }, [messages, onAppend]);
+
+    // When content size changes (images/cards), scroll to bottom if we were at bottom
+    const handleContentResize = React.useCallback(() => {
+        if (atBottomRef.current && containerRef.current) {
+            requestAnimationFrame(() => {
+                if (!containerRef.current) return;
+                containerRef.current.scrollTop = containerRef.current.scrollHeight;
+            });
+        }
+    }, []);
+
+    // For SSR safety: guard window usage (none required here)
+
+    return (
+        <div id={id} role="log" aria-live="polite" className={classList("common-chat-message-list", className)} ref={(el) => (containerRef.current = el)} style={style}>
+            {visibleMessages.map((m, i) => {
+                const globalIndex = startIndex + i;
+                const isLast = globalIndex === messages.length - 1;
+                return (
+                    <article
+                        key={m.id}
+                        ref={isLast ? (el) => (lastMessageRef.current = el) : undefined}
+                        className={classList("common-chat-message", m.author === "user" ? "from-user" : "from-agent")}
+                        aria-label={m.author ? `${m.author} ${m.timestamp ?? ""}` : undefined}
+                        role="article"
+                    >
+                        <div className="common-chat-message-meta">
+                            <div className="common-chat-message-author">{m.author}</div>
+                            {m.timestamp && <time className="common-chat-message-ts">{new Date(m.timestamp).toLocaleTimeString()}</time>}
+                        </div>
+                        <div className="common-chat-message-body">
+                            {m.parts.map((p: MessagePart, partIdx: number) => {
+                                const entry = mergedRegistry[p.kind] || unknownKindRenderer;
+                                const ctx: PartRenderContext = {
+                                    message: m,
+                                    partIndex: partIdx,
+                                    uiState: uiState[m.id],
+                                    updateUiState: (slot: string, v: any) => updateUiState(m.id, slot, v),
+                                    onContentResize: handleContentResize,
+                                };
+                                return (
+                                    <div className={classList("common-chat-message-part", `kind-${p.kind}`)} key={partIdx}>
+                                        {entry.render(p as any, ctx)}
+                                    </div>
+                                );
+                            })}
+                        </div>
+                    </article>
+                );
+            })}
+        </div>
+    );
+};
+
+export default ChatMessageList;
diff --git a/react-common/components/controls/Chat/README.md b/react-common/components/controls/Chat/README.md
new file mode 100644
index 000000000000..8c937a986dd2
--- /dev/null
+++ b/react-common/components/controls/Chat/README.md
@@ -0,0 +1,59 @@
+# Chat
+
+React Common Chat component
+
+This directory contains a basic chat UI component used as a lightweight, extensible chat/transcript UI.
+
+Main exports:
+
+- `Chat` — top-level composite rendering a message list and composer
+- `ChatMessageList` — list-only rendering with tail-biased windowing and bottom-anchoring
+- `ChatComposer` — a small composer input using `textarea` and `Button` for sending
+- `ChatTypes` — typed serializable message parts and envelopes
+
+Usage example:
+
+```
+import { Chat } from 'react-common/components/controls/Chat/Chat';
+import { Message } from 'react-common/components/controls/Chat/chat.types';
+
+const [messages, setMessages] = React.useState<Message[]>([]);
+
+<Chat
+  messages={messages}
+  onSend={(messageOrText) => {
+    if (typeof messageOrText === 'string') {
+      // lightweight convenience: composer returns text; build a Message
+      const m: Message = { id: String(Date.now()), author: 'user', timestamp: new Date().toISOString(), parts: [{ kind: 'text', text: messageOrText }] };
+      setMessages(prev => [...prev, m]);
+    } else {
+      setMessages(prev => [...prev, messageOrText]);
+    }
+  }}
+/>
+```
+
+The component uses the `Chat` registry pattern — a serializable message transcript contains `Message` objects with `parts` where each part has a `kind`. A registry maps `kind -> renderer` to render parts without embedding JSX/closures inside the transcript.
+
+The project includes minimal stories (storybook) and tests in `Chat.stories.tsx` and `Chat.test.tsx` in this folder.
+
+The component respects theming tokens via CSS variables (e.g., `--pxt-neutral-background1`, `--pxt-primary-background`). See `react-common/styles/theming/base-theme.less` for available tokens.
+
+Accessibility notes:
+
+- The message container uses `role="log"` and `aria-live="polite"`.
+- The composer uses a standard `textarea` with keyboard send (`Enter`) and `Shift+Enter` for newline.
+- Images include `alt` text when available.
+
+Serialization:
+
+- `exportEnvelope` / `importEnvelope` helpers provide a typed export/import boundary for transcripts. Attachments are referenced by `contentId` and handled via an optional attachment manifest.
+
+Migration:
+
+- Parts may include `version` and registry entries can provide a `migrate` hook. The current default schema version is exported from `chat.types.ts` as `CHAT_SCHEMA_VERSION`.
+
+Notes/TODOs:
+
+- The list uses a small tail-window windowing strategy; swap in a dedicated virtualizer later for heavy transcripts.
+- Registry `card` entries are demonstrated via a small demo card; consumers should register target-specific cards with stateful behavior using the provided `updateUiState` callback.
diff --git a/react-common/components/controls/Chat/chat.registry.tsx b/react-common/components/controls/Chat/chat.registry.tsx
new file mode 100644
index 000000000000..ce1dd2b4f6a7
--- /dev/null
+++ b/react-common/components/controls/Chat/chat.registry.tsx
@@ -0,0 +1,97 @@
+import * as React from "react";
+import { classList } from "../../util";
+import { Message, MessagePart, TextPart, ImagePart } from "./chat.types";
+
+export type PartRenderContext = {
+    message: Message;
+    partIndex: number;
+    // ephemeral UI state map for the message; consumers can store per-message UI state here
+    uiState?: any;
+    // update a named slot in the message UI state
+    updateUiState?: (slot: string, value: any) => void;
+    // callback invoked when a part's rendered content changes size (images, cards)
+    onContentResize?: () => void;
+};
+
+export interface RegistryEntry<TPart extends MessagePart = MessagePart> {
+    /** Render a part to JSX given a context. Must be pure with respect to transcript data. */
+    render: (part: TPart, ctx: PartRenderContext) => JSX.Element | null;
+    /** Optional migrate hook for upgrading older part versions */
+    migrate?: (part: TPart) => TPart;
+}
+
+export type ChatRegistry = { [kind: string]: RegistryEntry };
+
+// Minimal fallback renderer
+const fallbackRenderer: RegistryEntry = {
+    render: (part: MessagePart, ctx: PartRenderContext) => {
+        try {
+            // Show a safe description of the part
+            return (
+                <pre className={classList("common-chat-part-fallback")} aria-hidden={true}>
+                    {JSON.stringify(part, null, 2)}
+                </pre>
+            );
+        } catch (e) {
+            return <div className="common-chat-part-fallback">Unsupported message part</div>;
+        }
+    },
+};
+
+// A tiny demo card to show registry behavior in stories/tests
+const demoCardEntry: RegistryEntry = {
+    render: (part: MessagePart, ctx: PartRenderContext) => {
+        const card = (part as any) || {};
+        const count = (ctx?.uiState?.count as number) ?? 0;
+        return (
+            <div className={classList("common-chat-demo-card")}>
+                <div className="common-chat-demo-card-body">{card.title || "Card"}</div>
+                <div className="common-chat-demo-card-actions">
+                    <button className={classList("common-button")} onClick={() => ctx?.updateUiState?.("count", (count || 0) + 1)}>
+                        + {count}
+                    </button>
+                </div>
+            </div>
+        );
+    },
+    migrate: (part: MessagePart) => {
+        return part;
+    },
+};
+
+// default registry entries for text and image
+export const defaultRegistry: ChatRegistry = {
+    text: {
+        render: (part: TextPart) => {
+            return <div className="common-chat-part-text">{part.text}</div>;
+        },
+    },
+    image: {
+        render: (part: ImagePart, ctx) => {
+            const handleLoad = () => {
+                ctx?.onContentResize?.();
+            };
+            return <img src={part.src} alt={part.alt || ""} className={classList("common-chat-part-image")} onLoad={handleLoad} loading="lazy" />;
+        },
+    },
+    card: demoCardEntry,
+    // fallback (unknown kinds) will be handled by the list renderer by falling back to fallbackRenderer
+};
+
+export function createRegistry(overrides?: ChatRegistry): ChatRegistry {
+    if (!overrides) return defaultRegistry;
+    return Object.assign({}, defaultRegistry, overrides);
+}
+
+export function registerKind(registry: ChatRegistry, kind: string, entry: RegistryEntry) {
+    registry[kind] = entry;
+}
+
+export const unknownKindRenderer: RegistryEntry = fallbackRenderer;
+
+export default {
+    defaultRegistry,
+    createRegistry,
+    demoCardEntry,
+    unknownKindRenderer,
+};
diff --git a/react-common/components/controls/Chat/chat.serialization.ts b/react-common/components/controls/Chat/chat.serialization.ts
new file mode 100644
index 000000000000..1d857033d448
--- /dev/null
+++ b/react-common/components/controls/Chat/chat.serialization.ts
@@ -0,0 +1,49 @@
+import { ChatEnvelope, Message, AttachmentManifest, CHAT_SCHEMA_VERSION } from "./chat.types";
+
+export function exportEnvelope(messages: Message[], attachments?: AttachmentManifest): ChatEnvelope {
+    // Ensure a minimal, serializable copy (no functions/JSX)
+    const safeMessages = messages.map((m) => ({ ...m, parts: m.parts.map((p) => ({ ...p })) }));
+    return {
+        schemaVersion: CHAT_SCHEMA_VERSION,
+        exportedAt: new Date().toISOString(),
+        messages: safeMessages,
+        attachments,
+    };
+}
+
+export function exportEnvelopeToJson(messages: Message[], attachments?: AttachmentManifest): string {
+    return JSON.stringify(exportEnvelope(messages, attachments));
+}
+
+export function importEnvelope(raw: string | any): ChatEnvelope {
+    let obj: any;
+    if (typeof raw === "string") {
+        obj = JSON.parse(raw);
+    } else {
+        obj = raw;
+    }
+
+    if (!obj || typeof obj !== "object") throw new Error("Invalid envelope: not an object");
+    const schemaVersion = obj.schemaVersion || 0;
+    if (schemaVersion !== CHAT_SCHEMA_VERSION) {
+        // TODO: Add migration here
+        throw new Error(`Unsupported envelope schemaVersion: ${schemaVersion}`);
+    }
+
+    const messages: Message[] = (obj.messages || []).map((m: any) => ({
+        id: m.id,
+        parts: (m.parts || []).map((p: any) => ({ ...p })),
+        author: m.author,
+        timestamp: m.timestamp,
+        metadata: m.metadata,
+    }));
+
+    const attachments: AttachmentManifest | undefined = obj.attachments;
+
+    return {
+        schemaVersion,
+        exportedAt: obj.exportedAt || new Date().toISOString(),
+        messages,
+        attachments,
+    };
+}
diff --git a/react-common/components/controls/Chat/chat.stories.tsx b/react-common/components/controls/Chat/chat.stories.tsx
new file mode 100644
index 000000000000..ec4b0db6d194
--- /dev/null
+++ b/react-common/components/controls/Chat/chat.stories.tsx
@@ -0,0 +1,115 @@
+import * as React from "react";
+import Chat from "./Chat";
+import { Message } from "./chat.types";
+import { createRegistry } from "./chat.registry";
+
+export default {
+    title: "Controls/Chat",
+    component: Chat,
+};
+
+const sampleMessages: Message[] = [
+    {
+        id: "1",
+        author: "assistant",
+        timestamp: new Date().toISOString(),
+        parts: [{ kind: "text", text: "Hello! I'm a demo assistant." }],
+    },
+    {
+        id: "2",
+        author: "user",
+        timestamp: new Date().toISOString(),
+        parts: [{ kind: "text", text: "Hi — can you show an image?" }],
+    },
+    {
+        id: "3",
+        author: "assistant",
+        timestamp: new Date().toISOString(),
+        parts: [{ kind: "image", src: "https://via.placeholder.com/240x120.png?text=Demo+Image", alt: "Demo image" }],
+    },
+];
+
+export const Default = () => {
+    const [messages, setMessages] = React.useState<Message[]>(sampleMessages);
+    return (
+        <div style={{ height: 420, width: 420 }}>
+            <Chat
+                messages={messages}
+                onSend={(msgOrText: any) => {
+                    const toAppend: Message =
+                        typeof msgOrText === "string"
+                            ? {
+                                  id: `${Date.now()}`,
+                                  author: "user",
+                                  timestamp: new Date().toISOString(),
+                                  parts: [{ kind: "text", text: msgOrText }],
+                              }
+                            : msgOrText;
+                    setMessages((prev) => [...prev, toAppend]);
+                }}
+            />
+        </div>
+    );
+};
+
+export const WithCustomCard = () => {
+    const registry = createRegistry({
+        card: {
+            render: (part: any, ctx) => {
+                const count = ctx?.uiState?.count || 0;
+                return (
+                    <div style={{ border: "1px solid var(--pxt-neutral-stencil1)", padding: "0.5rem", borderRadius: "0.25rem" }}>
+                        <div>{part.title || "Demo Card"}</div>
+                        <div style={{ marginTop: "0.5rem" }}>
+                            <button className="common-button" onClick={() => ctx.updateUiState?.("count", count + 1)}>
+                                Click +{count}
+                            </button>
+                        </div>
+                    </div>
+                );
+            },
+        },
+    });
+
+    const [messages, setMessages] = React.useState<Message[]>([
+        { id: "c1", author: "assistant", timestamp: new Date().toISOString(), parts: [{ kind: "card", cardId: "demo", props: { title: "Counter Card" } }] },
+    ]);
+
+    return (
+        <div style={{ height: 420, width: 420 }}>
+            <Chat
+                messages={messages}
+                registry={registry}
+                onSend={(mOrText: any) => {
+                    const toAppend: Message =
+                        typeof mOrText === "string" ? { id: `${Date.now()}`, author: "user", timestamp: new Date().toISOString(), parts: [{ kind: "text", text: mOrText }] } : mOrText;
+                    setMessages((prev) => [...prev, toAppend]);
+                }}
+            />
+        </div>
+    );
+};
+
+export const LongTranscript = () => {
+    const many: Message[] = [];
+    for (let i = 0; i < 400; ++i) {
+        many.push({ id: `${i}`, author: i % 2 ? "user" : "assistant", timestamp: new Date().toISOString(), parts: [{ kind: "text", text: `Message #${i}` }] });
+    }
+
+    const [messages, setMessages] = React.useState<Message[]>(many);
+
+    return (
+        <div style={{ height: 420, width: 420 }}>
+            <Chat
+                messages={messages}
+                onSend={(mOrText: any) => {
+                    const toAppend: Message =
+                        typeof mOrText === "string" ? { id: `${Date.now()}`, author: "user", timestamp: new Date().toISOString(), parts: [{ kind: "text", text: mOrText }] } : mOrText;
+                    setMessages((prev) => [...prev, toAppend]);
+                }}
+                tailSize={40}
+                overscan={8}
+            />
+        </div>
+    );
+};
diff --git a/react-common/components/controls/Chat/chat.types.ts b/react-common/components/controls/Chat/chat.types.ts
new file mode 100644
index 000000000000..cd705e48a188
--- /dev/null
+++ b/react-common/components/controls/Chat/chat.types.ts
@@ -0,0 +1,67 @@
+// Chat public types and serialization envelope
+
+export const CHAT_SCHEMA_VERSION = 1;
+
+export type PartKind = string;
+
+/** Base for message parts; implementations should keep values serializable */
+export interface MessagePartBase {
+    kind: string; // semantic kind name
+    version?: number; // part schema version
+    // any additional serializable fields are allowed
+    [k: string]: any;
+}
+
+export interface TextPart extends MessagePartBase {
+    kind: "text";
+    text: string;
+}
+
+export interface ImagePart extends MessagePartBase {
+    kind: "image";
+    src: string; // content-addressable URL or data URL
+    alt?: string;
+    width?: number;
+    height?: number;
+}
+
+export interface CardPart extends MessagePartBase {
+    kind: "card";
+    cardId: string; // application-specific card identifier
+    props?: any; // serializable card props
+}
+
+export type MessagePart = TextPart | ImagePart | CardPart | MessagePartBase;
+
+export interface Message {
+    id: string; // unique, stable identifier for the message
+    parts: MessagePart[];
+    author?: string; // e.g. "user", "assistant", or client id
+    timestamp?: string; // ISO timestamp
+    metadata?: any; // optional opaque metadata
+}
+
+export interface AttachmentManifestEntry {
+    contentId: string; // opaque content-addressable id
+    contentType: string; // mime-type
+    size?: number;
+    metadata?: any;
+}
+
+export type AttachmentManifest = { [contentId: string]: AttachmentManifestEntry };
+
+export interface ChatEnvelope {
+    schemaVersion: number;
+    exportedAt: string; // ISO date
+    messages: Message[];
+    attachments?: AttachmentManifest;
+}
+
+// Utility helper: shallow-clone a Message with a new id (used by composer examples)
+export function cloneMessageWithId(message: Message, newId: string): Message {
+    return {
+        ...message,
+        id: newId,
+        parts: message.parts.map((p) => ({ ...p })),
+    };
+}
diff --git a/react-common/styles/controls/Chat.less b/react-common/styles/controls/Chat.less
new file mode 100644
index 000000000000..40464efca10b
--- /dev/null
+++ b/react-common/styles/controls/Chat.less
@@ -0,0 +1,122 @@
+/* Chat component styles: lightweight, theme-aware using CSS variables */
+
+.common-chat {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    height: 100%;
+    background-color: var(--pxt-neutral-background2);
+    color: var(--pxt-neutral-foreground2);
+    border-radius: 0.5rem;
+    border: 1px solid var(--pxt-neutral-stencil1);
+    overflow: hidden;
+}
+
+.common-chat-message-list {
+    flex: 1 1 auto;
+    overflow-y: auto;
+    padding: 0.5rem;
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+}
+
+.common-chat-message {
+    display: flex;
+    flex-direction: column;
+    max-width: 100%;
+}
+
+.common-chat-message.from-user {
+    align-items: flex-end;
+}
+
+.common-chat-message.from-agent {
+    align-items: flex-start;
+}
+
+.common-chat-message-meta {
+    display: flex;
+    flex-direction: row;
+    gap: 0.5rem;
+    font-size: 0.75rem;
+    color: var(--pxt-neutral-foreground3);
+}
+
+.common-chat-message-body {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    margin-top: 0.25rem;
+}
+
+.common-chat-message-part {
+    max-width: 72%;
+}
+
+.common-chat-part-text {
+    background: var(--pxt-neutral-background1);
+    color: var(--pxt-neutral-foreground1);
+    padding: 0.6rem 0.75rem;
+    border-radius: 0.5rem;
+    box-shadow: 0 1px 0 rgba(0,0,0,0.02);
+    white-space: pre-wrap;
+}
+
+.common-chat-part-image {
+    max-width: 18rem;
+    border-radius: 0.35rem;
+    border: 1px solid var(--pxt-neutral-stencil1);
+}
+
+.common-chat-composer {
+    display: flex;
+    gap: 0.5rem;
+    padding: 0.5rem;
+    border-top: 1px solid var(--pxt-neutral-stencil1);
+    background-color: var(--pxt-neutral-background1);
+}
+
+.common-chat-composer-textarea {
+    flex: 1 1 auto;
+    min-height: 2.5rem;
+    max-height: 10rem;
+    resize: none;
+    padding: 0.5rem;
+    border-radius: 0.25rem;
+    border: 1px solid var(--pxt-neutral-stencil1);
+    font-family: var(--page-font, "Segoe UI", Tahoma, Geneva, Verdana);
+}
+
+.common-chat-send-button {
+    align-self: flex-end;
+}
+
+.common-chat-part-fallback {
+    background: var(--pxt-neutral-background1);
+    color: var(--pxt-neutral-foreground1);
+    padding: 0.5rem;
+    border-radius: 0.3rem;
+    border: 1px dashed var(--pxt-neutral-stencil1);
+    font-family: var(--page-font, "Segoe UI", Tahoma, Geneva, Verdana);
+}
+
+.common-chat-demo-card {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+}
+
+/* small scroll to bottom helper */
+.common-chat-scroll-bottom {
+    position: absolute;
+    right: 1rem;
+    bottom: 4.25rem;
+}
+
+/* Respect reduced-motion */
+@media (prefers-reduced-motion: reduce) {
+    .common-chat-message-body {
+        transition: none !important;
+    }
+}
diff --git a/react-common/styles/react-common.less b/react-common/styles/react-common.less
index 6be6fc59f4cc..eccca6627cd9 100644
--- a/react-common/styles/react-common.less
+++ b/react-common/styles/react-common.less
@@ -22,6 +22,7 @@
 @import "controls/RadioButtonGroup.less";
 @import "controls/Spinner.less";
 @import "controls/Textarea.less";
+@import "controls/Chat.less";
 @import "controls/Tree.less";
 @import "controls/VerticalResizeContainer.less";
 @import "controls/VerticalSlider.less";
diff --git a/svgicons/chat.svg b/svgicons/chat.svg
new file mode 100644
index 000000000000..1e52a7997761
--- /dev/null
+++ b/svgicons/chat.svg
@@ -0,0 +1 @@
+<svg viewBox="0 0 315 362" xmlns="http://www.w3.org/2000/svg" fill-rule="evenodd" clip-rule="evenodd" stroke-linejoin="round" stroke-miterlimit="2"><path d="M67.379 361.038c-3.206-1.273-5.99-4.566-7.143-8.453-.876-2.948-1.109-8.759-1.109-27.822 0-18.159-.23-24.384-.935-25.26-.516-.637-3.133-1.737-5.814-2.443-2.682-.706-7.912-2.775-11.625-4.598-19.996-9.827-33.477-27.507-38.857-50.958-1.503-6.545-1.557-9.13-1.826-85.876-.181-51.673-.006-82.148.51-87.84C2.273 49.116 8.85 34.356 21.205 21.484 30.543 11.758 41.32 5.394 54.63 1.749L61.004.003h96.375c105.43 0 97.971-.28 110.098 4.173 20.826 7.647 36.896 25.494 44.19 49.079l2.085 6.749.213 87.375c.235 96.2.411 92.021-4.405 105.33-4.32 11.937-14.088 24.925-24.92 33.132-5.785 4.385-17.736 10.153-25.636 12.376-5.865 1.65-7.112 1.698-55.534 2.111-44.178.38-49.734.559-51.375 1.656-1.012.675-17.368 13.78-36.343 29.117-18.972 15.342-35.75 28.542-37.281 29.336-2.985 1.548-8.025 1.82-11.092.601zm46.893-58.785c14.7-11.962 27.967-22.425 29.48-23.25 2.657-1.445 4.559-1.513 54.503-1.888l51.749-.385 6.001-2.024c13.94-4.703 23.876-13.436 30.112-26.473 4.876-10.196 4.734-7.29 4.748-97.225.015-87.206.029-86.826-3.738-96.858-.899-2.392-3.308-6.854-5.355-9.91-5.95-8.897-13.947-15.023-24.766-18.978l-5.502-2.01-91.5-.212c-102.725-.238-97.209-.504-109.072 5.29-8.804 4.303-16.495 11.959-20.888 20.8-6.188 12.45-5.792 5.443-5.792 101.625v85.499l2.044 6.001c6.88 20.203 22.357 32.477 43.756 34.702 12.725 1.32 13.076 2.046 13.076 26.949 0 19.375.221 20.806 3.138 20.316.703-.12 13.306-10.004 28.006-21.969zm-30.665-67.465c-3.824-1.371-7.064-4.566-7.98-7.866-.408-1.468-.742-11.489-.745-22.272-.003-17.909.116-19.751 1.375-21.305 1.675-2.069 4.918-2.151 8.495-.215 1.82.983 4.133 1.352 8.502 1.35 7.253-.007 11.752-2.005 16.783-7.465 4.751-5.153 6.432-9.362 6.446-16.137.015-6.888-2.233-12.252-7.154-17.07-4.513-4.42-9.014-6.45-15.08-6.8-4.19-.245-5.701.028-9.278 1.666-5.375 2.46-6.597 2.45-8.58-.077-1.554-1.975-1.591-2.576-1.367-22.311.218-19.33.306-20.407 1.865-22.907 3.249-5.213 3.453-5.25 28.9-5.25 27.118 0 26.32.21 24.247-6.375-4.669-14.845 5.168-30.87 20.432-33.284 8.748-1.38 17.419 1.346 23.434 7.376 6.724 6.74 9.179 16.82 6.31 25.93-2.055 6.538-2.733 6.353 23.247 6.356 31.161.003 29.14-1.961 29.67 28.837l.374 21.784 3-.175c14.38-.854 18.53.23 24.599 6.406 5.057 5.148 6.88 9.658 6.88 17.02 0 6.978-1.54 11.114-5.962 16.006-5.423 6.004-15.602 9.015-23.244 6.874-5.695-1.593-5.55-2.137-5.803 21.997-.215 20.744-.252 21.167-1.967 23.573-3.838 5.38 1.23 5.032-75.504 5.213-57.262.133-69.491-.014-71.895-.879z" fill-rule="nonzero"/></svg>
\ No newline at end of file

From d45a6bf5b28375d9ec42c4cb424de2da5064c1a7 Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Tue, 2 Sep 2025 17:46:02 -0700
Subject: [PATCH 03/16] sidedoc rework wip

---
 theme/sidedoc.less       | 211 ++++++++++++++++++--------------
 webapp/src/container.tsx | 251 +++++++++++++++++++++++++++++++++------
 2 files changed, 339 insertions(+), 123 deletions(-)

diff --git a/theme/sidedoc.less b/theme/sidedoc.less
index 3c62c9f6d8d4..c4250831df53 100644
--- a/theme/sidedoc.less
+++ b/theme/sidedoc.less
@@ -1,6 +1,6 @@
 /* Import all components */
-@import 'themes/default/globals/site.variables';
-@import 'themes/pxt/globals/site.variables';
+@import "themes/default/globals/site.variables";
+@import "themes/pxt/globals/site.variables";
 
 /* Reference import */
 @import (reference) "semantic.less";
@@ -11,12 +11,14 @@
 
 /* Side Docs layout */
 #sidedocs {
-  top: 0;
-  z-index: @sidedocZIndex;
-  visibility: hidden;
-  opacity: 0;
-  right: 0;
-  width: 0;
+    top: 0;
+    z-index: @sidedocZIndex;
+    visibility: hidden;
+    opacity: 0;
+    right: 0;
+    width: 0;
+    /* Animate width/right/opacity so the side panel transitions with the same timing as the tabs */
+    transition: width 0.25s ease, right 0.25s ease, opacity 0.25s ease;
 }
 
 code.hljs {
@@ -24,28 +26,43 @@ code.hljs {
 }
 
 #sidedocsbar {
-  position: absolute;
-  right: 1rem;
+    position: absolute;
+    right: 1rem;
 }
 
 #sidedocsframe {
-  width: 0;
-  height: 0;
-  border:none;
-  background: white;
-}
-
-/* Side docs toggle button */
-#sidedocstoggle {
-  right: 0;
-  left: auto;
+    width: 0;
+    height: 0;
+    border: none;
+    background: white;
+}
+
+/* Close button inside the SideDocs panel (top-right) */
+#sidedocsframe-wrapper .sidedocs-close {
+    position: absolute;
+    top: 0.5rem;
+    right: 0.5rem;
+    z-index: @sidedocZIndex + 2;
+    background: transparent;
+    border: none;
+    color: var(--pxt-neutral-foreground1);
+    opacity: 0.9;
+    padding: 0.25rem;
+    line-height: 1;
+}
+
+#sidedocsframe-wrapper .sidedocs-close:hover,
+#sidedocsframe-wrapper .sidedocs-close:focus {
+    opacity: 1;
 }
 
 .sideDocs #sidedocs {
     position: fixed;
     visibility: visible;
     opacity: 1;
-    width: @sideBarWidth;
+    width: var(--sidedocWidth);
+    /* Don't let the panel expand beyond a fraction of the viewport */
+    max-width: 50vw;
     top: calc(@mainMenuHeight + 1rem);
     height: ~"calc(100% - @{mainMenuHeight} - @{editorToolsCollapsedHeight} - 2rem)";
 }
@@ -54,31 +71,28 @@ code.hljs {
     position: relative;
     -webkit-overflow-scrolling: touch;
     overflow: auto;
-    width: @sideBarWidth;
+    width: var(--sidedocWidth);
     height: 100%;
-    -webkit-box-shadow: 0px 0px 20px 0px rgba(0,0,0,0.41);
-    -moz-box-shadow: 0px 0px 20px 0px rgba(0,0,0,0.41);
-    box-shadow: 0px 0px 20px 0px rgba(0,0,0,0.41);
+    -webkit-box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
+    -moz-box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
+    box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
     border-top-left-radius: 5px;
     border-bottom-left-radius: 5px;
     z-index: @sidedocZIndex;
 
     &:has(aside:focus-visible) {
-        outline: @editorFocusBorderSize solid  var(--pxt-focus-border);
+        outline: @editorFocusBorderSize solid var(--pxt-focus-border);
     }
 }
 
 .sideDocs #sidedocsframe {
-  position:absolute;
-  top:0px;
-  width:100%;
-  height:100%;
+    position: absolute;
+    top: 0px;
+    width: 100%;
+    height: 100%;
 }
 
-.sideDocs #sidedocstoggle {
-   right: @sideBarWidth;
-   transition: right 0.5s, opacity 0.5s linear;
-}
+/* The old sidedocstoggle control was removed; the new close button is inside #sidedocsframe-wrapper */
 
 .sideDocs #sidedocsbar {
     top: 1rem;
@@ -86,89 +100,112 @@ code.hljs {
 }
 
 #sidedocsbar .ui.link .icon {
-  cursor: pointer;
-  font-size: @h3;
+    cursor: pointer;
+    font-size: @h3;
 }
 
 /* Sidedocs in Monaco editor */
 .sideDocs.editorlang-text {
     #sidedocs {
-        width: 50%!important;
+        width: 50% !important;
         min-width: 18rem;
     }
 
-    #sidedocsframe, #sidedocsframe-wrapper {
-        width: 100%!important;
-    }
-
-    #sidedocstoggle {
-        right: calc(~'50% - 0.5rem')!important;
+    #sidedocsframe,
+    #sidedocsframe-wrapper {
+        width: 100% !important;
     }
 
-    @media only screen and (max-width: 36rem) {
-        #sidedocstoggle {
-            right: 17rem!important;
-        }
-    }
+    /* The old sidedocstoggle control was removed; the new close button is inside #sidedocsframe-wrapper */
 }
 
 /* Large Monitor */
 @media only screen and (min-width: @largeMonitorBreakpoint) {
-    .sideDocs #sidedocs, .sideDocs #sidedocsframe, .sideDocs #sidedocsframe-wrapper {
-        width: @sideBarWidthLarge !important;
-    }
-    .sideDocs #sidedocstoggle {
-        right: @sideBarWidthLarge !important;
-    }
+    /* override the CSS variable used by the panel and tabs */
+    .sideDocs { --sidedocWidth: ~"min(@{sideBarWidthLarge}, 50vw)"; }
+    /* The old sidedocstoggle control was removed; the new close button is inside #sidedocsframe-wrapper */
 }
 
 /* Small Monitor */
 @media only screen and (min-width: @computerBreakpoint) and (max-width: @largestSmallMonitor) {
-
 }
 
 /* Tablet */
 @media only screen and (min-width: @tabletBreakpoint) and (max-width: @largestTabletScreen) {
-
 }
 
 /* Mobile */
 @media only screen and (max-width: @largestMobileScreen) {
-
-}
-
-/* >= Small Monitor (Small Monitor + Large Monitor + Wide Monitor) */
-@media only screen and (min-width: @computerBreakpoint) {
+    /* override the CSS variable used by the panel and tabs on mobile */
+    .sideDocs { --sidedocWidth: ~"min(@{sideBarWidthSmall}, 50vw)"; }
+    /* The old sidedocstoggle control was removed; the new close button is inside #sidedocsframe-wrapper */
+     /* position the tabstrip appropriately on mobile */
+     #sidedocstabs, .sidedoc-tablist {
+         top: calc(@mobileMenuHeight + 8px);
+     }
 }
 
-/* <= Small Monitor (Mobile + Tablet + Small Monitor) */
-@media only screen and (max-width: @largestSmallMonitor) {
-
-}
-
-/* <= Tablet (Mobile + Tablet) */
-@media only screen and (max-width: @largestTabletScreen) {
+@media only screen and (max-height: @tallEditorBreakpoint) and (min-width: @largestMobileScreen) {
     .sideDocs #sidedocs {
-        top: calc(@mobileMenuHeight + 1rem);
-        height: ~"calc(100% - @{mobileMenuHeight} - @{editorToolsHeight} - 2rem)";
-    }
-    .sideDocs.collapsedEditorTools #sidedocs, .sideDocs.hideEditorFloats #sidedocs {
-        height: ~"calc(100% - @{mobileMenuHeight} - @{editorToolsCollapsedHeight} - 2rem)";
+        top: calc(@thinMenuHeight + 1rem);
     }
 }
 
-/* Mobile */
-@media only screen and (max-width: @largestMobileScreen) {
-    .sideDocs #sidedocs, .sideDocs #sidedocsframe, .sideDocs #sidedocsframe-wrapper {
-        width: @sideBarWidthSmall !important;
-    }
-    .sideDocs #sidedocstoggle {
-        right: @sideBarWidthSmall !important;
-    }
+/* Side docs tab strip styles */
+#sidedocstabs,
+.sidedoc-tablist {
+    position: fixed;
+    right: 0;
+    top: calc(@mainMenuHeight + 8px);
+    display: flex;
+    flex-direction: column;
+    z-index: @sidedocZIndex + 1;
+    gap: 0.35rem;
+    padding: 0.25rem;
+    /* no transition by default (instant close on collapse) */
+    transition: none;
+}
+
+/* When the sidebar is open, define the clamped width value for use by the panel and the tabstrip */
+.sideDocs {
+    --sidedocWidth: ~"min(@{sideBarWidth}, 50vw)";
+}
+
+/* When the sidebar is open (body .sideDocs), move the tab strip to the panel edge */
+.sideDocs #sidedocstabs {
+    /* place the tab strip at the same clamped width used by the panel */
+    right: var(--sidedocWidth);
+    transition: right 0.25s ease;
+}
+
+.sidedoc-tab {
+    width: 2.5rem;
+    height: 2.5rem;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 0.35rem;
+    background: var(--pxt-neutral-alpha10);
+    color: var(--pxt-neutral-foreground1);
+    cursor: pointer;
+    border: 1px solid transparent;
+}
+
+.sidedoc-tab.active {
+    background: var(--pxt-neutral-alpha20);
+    border-color: var(--pxt-secondary-accent);
+}
+
+/* Make the inner button fill the tab wrapper */
+.sidedoc-tab .ui.button {
+    width: 100%;
+    height: 100%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: transparent;
+    border: none;
+    padding: 0;
+    margin: 0;
+    box-shadow: none;
 }
-
-@media only screen and (max-height: @tallEditorBreakpoint) and (min-width: @largestMobileScreen) {
-    .sideDocs #sidedocs {
-        top: calc(@thinMenuHeight + 1rem);
-    }
-}
\ No newline at end of file
diff --git a/webapp/src/container.tsx b/webapp/src/container.tsx
index b387310cbbe9..269832cf9d15 100644
--- a/webapp/src/container.tsx
+++ b/webapp/src/container.tsx
@@ -792,15 +792,29 @@ export class EditorSelector extends data.Component<IEditorSelectorProps, {}> {
     }
 }
 
+export interface SideDocsTab {
+    id: string;
+    title?: string;
+    icon?: string;
+    component?: () => JSX.Element;
+    builtInKey?: pxt.editor.BuiltInHelp;
+}
+
 export interface SideDocsProps extends ISettingsProps {
     docsUrl: string;
     sideDocsCollapsed: boolean;
+    extraTabs?: SideDocsTab[]; // dynamic tabs passed from parent
+    showBuiltIns?: boolean; // defaults to true
 }
 
 // This Component overrides shouldComponentUpdate, be sure to update that if the state is updated
 export interface SideDocsState {
-    docsUrl?: string;
+    // docsIframeUrl stores the last non-built-in docs URL used by the iframe tab.
+    docsIframeUrl?: string;
     sideDocsCollapsed?: boolean;
+    activeTabId?: string;
+    sideDocsWidthPx?: number;
+    tabsTopPx?: number;
 }
 
 
@@ -826,11 +840,17 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
     constructor(props: SideDocsProps) {
         super(props);
         this.state = {
+            docsIframeUrl: undefined,
+            sideDocsCollapsed: undefined,
+            activeTabId: 'docs-iframe',
+            sideDocsWidthPx: 0,
+            tabsTopPx: 48
         }
 
         this.toggleVisibility = this.toggleVisibility.bind(this);
         this.notifyPopOut = this.notifyPopOut.bind(this);
         this.close = this.close.bind(this);
+        this.updateLayoutMeasurements = this.updateLayoutMeasurements.bind(this);
     }
 
     private rootDocsUrl(): string {
@@ -856,20 +876,22 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         if (query && docsUrl.endsWith("#")) docsUrl = docsUrl.substr(0, docsUrl.length - 1) + query + "#";
         const url = `${docsUrl}doc:${path}:${mode}:${pxt.Util.localeInfo()}`;
         this.setUrl(url);
+        this.setState({ activeTabId: 'docs-iframe' });
     }
 
     setMarkdown(md: string) {
         const docsUrl = this.rootDocsUrl();
         // always render blocks by default when sending custom markdown
-        // to side bar
         const mode = "blocks" // this.props.parent.isBlocksEditor() ? "blocks" : "js";
         const url = `${docsUrl}md:${encodeURIComponent(md)}:${mode}:${pxt.Util.localeInfo()}`;
-        this.props.parent.setState({ sideDocsLoadUrl: url });
+        // Use setUrl so we keep internal iframe URL state in sync
+        this.setUrl(url);
     }
 
     toggleBuiltInHelp(help: pxt.editor.BuiltInHelp, focusIfVisible: boolean) {
         const url = `${builtInPrefix}${help}`;
-        const shouldCollapse = this.state.docsUrl === url && !this.state.sideDocsCollapsed && !focusIfVisible;
+        // determine collapse based on active tab id (built-in) rather than a shared url cache
+        const shouldCollapse = this.state.activeTabId === (help as string) && !this.state.sideDocsCollapsed && !focusIfVisible;
 
         pxt.tickEvent(
             `sidedocs.builtin`,
@@ -891,11 +913,19 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             this.openingSideDoc = true;
             Blockly.hideChaff(true);
             this.setUrl(url);
+            this.setState({ activeTabId: help as string });
         }
     }
 
     private setUrl(url: string) {
         this.props.parent.setState({ sideDocsLoadUrl: url, sideDocsCollapsed: false });
+        // store last non-built-in docs url in state.docsIframeUrl so iframe tab has its own url cache
+        if (!url.startsWith(builtInPrefix)) {
+            this.setState({ docsIframeUrl: url, activeTabId: 'docs-iframe' });
+        } else {
+            const key = this.getBuiltInKeyFromUrl(url);
+            if (key) this.setState({ activeTabId: key });
+        }
     }
 
     expand() {
@@ -918,18 +948,31 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
 
     toggleVisibility() {
         const state = this.props.parent.state;
-        this.props.parent.setState({ sideDocsCollapsed: !state.sideDocsCollapsed });
-        document.getElementById("sidedocstoggle").focus();
+        const nextCollapsed = !state.sideDocsCollapsed;
+        // If we're expanding the panel, set openingSideDoc so componentDidUpdate will focus the close button
+        if (!nextCollapsed) this.openingSideDoc = true;
+        this.props.parent.setState({ sideDocsCollapsed: nextCollapsed });
+    }
+
+    componentDidMount() {
+        window.addEventListener('resize', this.updateLayoutMeasurements);
+        this.updateLayoutMeasurements();
+    }
+
+    componentWillUnmount() {
+        window.removeEventListener('resize', this.updateLayoutMeasurements);
     }
 
     componentDidUpdate() {
         this.props.parent.editor.resize();
 
-        let sidedocstoggle = document.getElementById("sidedocstoggle");
-        if (this.openingSideDoc && sidedocstoggle) {
-            sidedocstoggle.focus();
+        let sidedocsclose = document.getElementById("sidedocsclose");
+        if (this.openingSideDoc && sidedocsclose) {
+            (sidedocsclose as HTMLElement).focus();
             this.openingSideDoc = false;
         }
+
+        this.updateLayoutMeasurements();
     }
 
     UNSAFE_componentWillReceiveProps(nextProps: SideDocsProps) {
@@ -938,14 +981,25 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             newState.sideDocsCollapsed = nextProps.sideDocsCollapsed;
         }
         if (nextProps.docsUrl != undefined) {
-            newState.docsUrl = nextProps.docsUrl;
+            // If incoming docsUrl indicates a built-in, set active tab accordingly; otherwise track it as the iframe URL
+            if (nextProps.docsUrl && nextProps.docsUrl.startsWith(builtInPrefix)) {
+                const key = this.getBuiltInKeyFromUrl(nextProps.docsUrl);
+                if (key) newState.activeTabId = key;
+                else newState.activeTabId = 'docs-iframe';
+            } else {
+                newState.docsIframeUrl = nextProps.docsUrl;
+                newState.activeTabId = 'docs-iframe';
+            }
         }
         if (Object.keys(newState).length > 0) this.setState(newState)
     }
 
     shouldComponentUpdate(nextProps: SideDocsProps, nextState: SideDocsState, nextContext: any): boolean {
         return this.state.sideDocsCollapsed != nextState.sideDocsCollapsed
-            || this.state.docsUrl != nextState.docsUrl;
+            || this.state.docsIframeUrl != nextState.docsIframeUrl
+            || this.state.activeTabId != nextState.activeTabId
+            || this.state.sideDocsWidthPx != nextState.sideDocsWidthPx
+            || this.state.tabsTopPx != nextState.tabsTopPx;
     }
 
     private handleKeyDown = (ev: React.KeyboardEvent<HTMLElement>) => {
@@ -955,21 +1009,93 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         }
     }
 
+    private getBuiltInKeyFromUrl(url: string): pxt.editor.BuiltInHelp | undefined {
+        if (url && url.startsWith(builtInPrefix)) {
+            return url.slice(builtInPrefix.length) as pxt.editor.BuiltInHelp;
+        }
+        return undefined;
+    }
+
+    private buildTabs(): SideDocsTab[] {
+        const tabs: SideDocsTab[] = [];
+        // persistent iframe docs tab
+        tabs.push({ id: 'docs-iframe', title: lf("Docs"), icon: "help circle" });
+
+        const showBuiltIns = this.props.showBuiltIns !== false;
+        if (showBuiltIns) {
+            for (const k in builtIns) {
+                const key = k as pxt.editor.BuiltInHelp;
+                const info = builtIns[key];
+                tabs.push({ id: key as string, title: pxt.Util.rlf(key), icon: "keyboard", component: info.component, builtInKey: key });
+            }
+        }
+
+        if (this.props.extraTabs) {
+            for (const et of this.props.extraTabs) {
+                const tid = et.id || `extra-${Math.random().toString(36).slice(2, 8)}`;
+                tabs.push({ id: tid, title: et.title, icon: et.icon, component: et.component });
+            }
+        }
+
+        return tabs;
+    }
+
+    private selectTab(tabId: string) {
+        const tabs = this.buildTabs();
+        const tab = tabs.find(t => t.id === tabId);
+        if (!tab) return;
+        if (tab.builtInKey) {
+            const url = builtInPrefix + tab.builtInKey;
+            this.setUrl(url);
+            this.setState({ activeTabId: tabId });
+        } else if (tab.id === 'docs-iframe') {
+            // prefer iframe-specific non-built-in url from our state; avoid accidentally using a built-in url stored on parent
+            const candidateFromState = this.state.docsIframeUrl;
+            const candidateFromProps = (this.props.docsUrl && !this.props.docsUrl.startsWith(builtInPrefix)) ? this.props.docsUrl : undefined;
+            const url = candidateFromState || candidateFromProps || this.rootDocsUrl();
+            this.setUrl(url);
+        } else if (tab.component) {
+            this.setState({ activeTabId: tabId });
+            this.props.parent.setState({ sideDocsLoadUrl: '', sideDocsCollapsed: false });
+        }
+    }
+
+    private updateLayoutMeasurements() {
+        const sidedocs = document.getElementById('sidedocs');
+        const mainmenu = document.getElementById('mainmenu');
+        const newState: Partial<SideDocsState> = {};
+        if (sidedocs) {
+            const r = sidedocs.getBoundingClientRect();
+            newState.sideDocsWidthPx = Math.round(r.width);
+        } else {
+            newState.sideDocsWidthPx = 0;
+        }
+        if (mainmenu) {
+            const r2 = mainmenu.getBoundingClientRect();
+            newState.tabsTopPx = Math.round(r2.bottom + 8);
+        } else {
+            newState.tabsTopPx = 48;
+        }
+        if (newState.sideDocsWidthPx !== this.state.sideDocsWidthPx || newState.tabsTopPx !== this.state.tabsTopPx) {
+            this.setState(newState as SideDocsState);
+        }
+    }
+
     renderCore() {
-        const { sideDocsCollapsed, docsUrl } = this.state;
-        const isRTL = pxt.Util.isUserLanguageRtl();
-        const showLeftChevron = (sideDocsCollapsed || isRTL) && !(sideDocsCollapsed && isRTL); // Collapsed XOR RTL
+        const tabs = this.buildTabs();
+        // If activeTabId is not set, defer to the incoming props to determine if the current prop url is a built-in.
+        const activeTabId = this.state.activeTabId || (this.props.docsUrl && this.props.docsUrl.startsWith(builtInPrefix) ? this.getBuiltInKeyFromUrl(this.props.docsUrl as string) || 'docs-iframe' : 'docs-iframe');
+        const activeTab = tabs.find(t => t.id === activeTabId) || tabs[0];
+
+        const { sideDocsCollapsed, docsIframeUrl } = this.state;
         const lockedEditor = !!pxt.appTarget.appTheme.lockedEditor;
 
-        if (!docsUrl) return null;
+        const url = (activeTab.id === 'docs-iframe') ? (sideDocsCollapsed ? this.rootDocsUrl() : (docsIframeUrl || (this.props.docsUrl && !this.props.docsUrl.startsWith(builtInPrefix) ? this.props.docsUrl : this.rootDocsUrl()))) : (activeTab.builtInKey ? `${builtInPrefix}${activeTab.builtInKey}` : '');
 
-        const url = sideDocsCollapsed ? this.rootDocsUrl() : docsUrl;
-        const builtIn = url.startsWith(`${builtInPrefix}`)
-            ? builtIns[url.slice(builtInPrefix.length) as pxt.editor.BuiltInHelp]
-            : undefined;
-        const openInNewTabLinkProps: React.ComponentProps<'a'> = builtIn ? {
+        const builtInDetail = url && url.startsWith(builtInPrefix) ? builtIns[url.slice(builtInPrefix.length) as pxt.editor.BuiltInHelp] : undefined;
+        const openInNewTabLinkProps: React.ComponentProps<'a'> = builtInDetail ? {
             target: "_blank",
-            href: builtIn.popOutHref,
+            href: builtInDetail.popOutHref,
             rel: "noopener",
             onClick: this.close,
         } : {
@@ -986,31 +1112,84 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         </div>;
 
         const content = <div key="content" id="sidedocsframe-wrapper">
-            {this.renderContent(url, builtIn, lockedEditor)}
+            {/* Close button in the top-right of the expanded panel */}
+            <sui.Button id="sidedocsclose" className={`sidedocs-close ui icon button`} icon="close" title={lf("Close the side documentation")} ariaLabel={lf("Close the side documentation")} onClick={this.close} />
+            {this.renderTabContent(activeTab, url, builtInDetail, lockedEditor)}
         </div>;
 
-        const flipNewTabLinkOrder = builtIn?.singleTabStop;
-
+        const flipNewTabLinkOrder = builtInDetail?.singleTabStop;
         const contentParts = flipNewTabLinkOrder ? [content, openInNewTab] : [openInNewTab, content];
 
         /* eslint-disable @microsoft/sdl/react-iframe-missing-sandbox */
         return <div>
-            <button id="sidedocstoggle" role="button" aria-label={sideDocsCollapsed ? lf("Expand the side documentation") : lf("Collapse the side documentation")} className="ui icon button large" onClick={this.toggleVisibility}>
-                <sui.Icon icon={`icon inverted chevron ${showLeftChevron ? 'left' : 'right'}`} />
-            </button>
-            <div id="sidedocs" onKeyDown={this.handleKeyDown}>
-                {contentParts}
-            </div>
-        </div>
-        /* eslint-enable @microsoft/sdl/react-iframe-missing-sandbox */
-    }
+            {/* tab strip */}
+             <div id="sidedocstabs" role="tablist" className="sidedoc-tablist" aria-orientation="vertical">
+                 {(() => {
+                     const onTabKeyDown = (ev: React.KeyboardEvent<HTMLElement>, idx: number) => {
+                         const key = ev.key;
+                         if (key === 'ArrowUp' || key === 'ArrowDown' || key === 'Home' || key === 'End') {
+                             ev.preventDefault();
+                             let newIdx = idx;
+                             if (key === 'ArrowUp') newIdx = (idx - 1 + tabs.length) % tabs.length;
+                             else if (key === 'ArrowDown') newIdx = (idx + 1) % tabs.length;
+                             else if (key === 'Home') newIdx = 0;
+                             else if (key === 'End') newIdx = tabs.length - 1;
+                             const tabBtn = document.getElementById('sidedocstabs')?.querySelectorAll('button')[newIdx] as HTMLButtonElement;
+                             if (tabBtn) {
+                                 tabBtn.focus();
+                                 // invoke selectTab directly to ensure state is in sync
+                                 this.selectTab(tabs[newIdx].id);
+                             }
+                         } else if (key === 'Escape') {
+                             this.collapse();
+                         }
+                     };
+ 
+                     return tabs.map((t, i) => {
+                         const isActive = t.id === activeTabId;
+                        return (
+                            <div key={t.id} title={t.title || ''} className={`sidedoc-tab ${isActive ? 'active' : ''}`}>
+                                <sui.Button
+                                    role="tab"
+                                    aria-selected={isActive}
+                                    ariaLabel={t.title || ''}
+                                    title={t.title || ''}
+                                    aria-controls="sidedocsframe-wrapper"
+                                    onClick={() => this.selectTab(t.id)}
+                                    onKeyDown={(ev: React.KeyboardEvent<HTMLElement>) => onTabKeyDown(ev, i)}
+                                    tabIndex={0}
+                                    icon={t.icon || "help"}
+                                    className={`sidedoc-tab-button`}
+                                />
+                            </div>
+                        );
+                     });
+                 })()}
+             </div>
+             <div id="sidedocs" onKeyDown={this.handleKeyDown}>
+                 {!sideDocsCollapsed ? contentParts : null}
+             </div>
+         </div>
+         /* eslint-enable @microsoft/sdl/react-iframe-missing-sandbox */
+     }
+
+    renderTabContent(tab: SideDocsTab, url: string, builtInDetail: BuiltInHelpDetails | undefined, lockedEditor: boolean) {
+        if (!tab) return null;
+        if (tab.component) {
+            const TabComponent = tab.component;
+            try {
+                return <TabComponent />;
+            } catch (e) {
+                return <div>{lf("Error rendering tab content")}</div>;
+            }
+        }
 
-    renderContent(url: string, builtIn: BuiltInHelpDetails | undefined, lockedEditor: boolean) {
-        const BuiltInComponent =  builtIn?.component;
+        // If no tab.component provided, fall back to iframe/built-in handling
+        const BuiltInComponent = builtInDetail?.component;
         return BuiltInComponent ? <BuiltInComponent /> : (
             <iframe id="sidedocsframe" src={url} title={lf("Documentation")} aria-atomic="true" aria-live="assertive"
                 sandbox={`allow-scripts allow-same-origin allow-forms ${lockedEditor ? "" : "allow-popups"}`} />
-        )
+        );
     }
 }
 

From cc5b02bd8ad866b8377e8cbfec3ba149abb18eea Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Wed, 3 Sep 2025 16:58:47 -0700
Subject: [PATCH 04/16] sidebar refactor wip

---
 theme/sidedoc.less       | 73 +++++++++++++++++++++++++++++++---------
 webapp/src/container.tsx | 14 ++++++--
 2 files changed, 68 insertions(+), 19 deletions(-)

diff --git a/theme/sidedoc.less b/theme/sidedoc.less
index c4250831df53..773419bd3e2e 100644
--- a/theme/sidedoc.less
+++ b/theme/sidedoc.less
@@ -39,21 +39,16 @@ code.hljs {
 
 /* Close button inside the SideDocs panel (top-right) */
 #sidedocsframe-wrapper .sidedocs-close {
-    position: absolute;
-    top: 0.5rem;
-    right: 0.5rem;
     z-index: @sidedocZIndex + 2;
     background: transparent;
     border: none;
     color: var(--pxt-neutral-foreground1);
-    opacity: 0.9;
     padding: 0.25rem;
     line-height: 1;
 }
 
 #sidedocsframe-wrapper .sidedocs-close:hover,
 #sidedocsframe-wrapper .sidedocs-close:focus {
-    opacity: 1;
 }
 
 .sideDocs #sidedocs {
@@ -68,9 +63,10 @@ code.hljs {
 }
 
 .sideDocs #sidedocsframe-wrapper {
+    display: flex;
+    flex-direction: column;
     position: relative;
-    -webkit-overflow-scrolling: touch;
-    overflow: auto;
+    overflow: hidden;
     width: var(--sidedocWidth);
     height: 100%;
     -webkit-box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
@@ -86,8 +82,6 @@ code.hljs {
 }
 
 .sideDocs #sidedocsframe {
-    position: absolute;
-    top: 0px;
     width: 100%;
     height: 100%;
 }
@@ -122,7 +116,9 @@ code.hljs {
 /* Large Monitor */
 @media only screen and (min-width: @largeMonitorBreakpoint) {
     /* override the CSS variable used by the panel and tabs */
-    .sideDocs { --sidedocWidth: ~"min(@{sideBarWidthLarge}, 50vw)"; }
+    .sideDocs {
+        --sidedocWidth: ~"min(@{sideBarWidthLarge}, 50vw)";
+    }
     /* The old sidedocstoggle control was removed; the new close button is inside #sidedocsframe-wrapper */
 }
 
@@ -137,12 +133,15 @@ code.hljs {
 /* Mobile */
 @media only screen and (max-width: @largestMobileScreen) {
     /* override the CSS variable used by the panel and tabs on mobile */
-    .sideDocs { --sidedocWidth: ~"min(@{sideBarWidthSmall}, 50vw)"; }
+    .sideDocs {
+        --sidedocWidth: ~"min(@{sideBarWidthSmall}, 50vw)";
+    }
     /* The old sidedocstoggle control was removed; the new close button is inside #sidedocsframe-wrapper */
-     /* position the tabstrip appropriately on mobile */
-     #sidedocstabs, .sidedoc-tablist {
-         top: calc(@mobileMenuHeight + 8px);
-     }
+    /* position the tabstrip appropriately on mobile */
+    #sidedocstabs,
+    .sidedoc-tablist {
+        top: calc(@mobileMenuHeight + 8px);
+    }
 }
 
 @media only screen and (max-height: @tallEditorBreakpoint) and (min-width: @largestMobileScreen) {
@@ -156,7 +155,7 @@ code.hljs {
 .sidedoc-tablist {
     position: fixed;
     right: 0;
-    top: calc(@mainMenuHeight + 8px);
+    top: calc(@mainMenuHeight + 12px);
     display: flex;
     flex-direction: column;
     z-index: @sidedocZIndex + 1;
@@ -209,3 +208,45 @@ code.hljs {
     margin: 0;
     box-shadow: none;
 }
+
+#sidedocsframe-wrapper .sidedoc-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0.25rem;
+    background: var(--pxt-header-background);
+    color: var(--pxt-primary-foreground);
+    z-index: @sidedocZIndex + 3;
+    min-height: fit-content;
+
+    .sidedoc-header-spacer {
+        flex-grow: 1;
+    }
+}
+
+#sidedocsframe-wrapper .sidedoc-title {
+    font-weight: 600;
+    font-size: 1rem;
+    line-height: 1;
+    margin: 0;
+}
+
+/* close button in header */
+#sidedocsframe-wrapper .sidedocs-close {
+    background: transparent;
+    border: none;
+    color: var(--pxt-neutral-foreground1);
+    opacity: 0.95;
+}
+
+#sidedocsframe-wrapper .sidedocs-close:hover,
+#sidedocsframe-wrapper .sidedocs-close:focus {
+    opacity: 1;
+}
+
+/* content area below header */
+#sidedocsframe-wrapper .sidedocs-content {
+    flex-grow: 1;
+    overflow: auto;
+    -webkit-overflow-scrolling: touch;
+}
diff --git a/webapp/src/container.tsx b/webapp/src/container.tsx
index 269832cf9d15..1322f9052717 100644
--- a/webapp/src/container.tsx
+++ b/webapp/src/container.tsx
@@ -805,6 +805,7 @@ export interface SideDocsProps extends ISettingsProps {
     sideDocsCollapsed: boolean;
     extraTabs?: SideDocsTab[]; // dynamic tabs passed from parent
     showBuiltIns?: boolean; // defaults to true
+    sideDocsTitle?: React.ReactNode; // title to show in the side docs header
 }
 
 // This Component overrides shouldComponentUpdate, be sure to update that if the state is updated
@@ -1111,10 +1112,17 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             </a>
         </div>;
 
-        const content = <div key="content" id="sidedocsframe-wrapper">
-            {/* Close button in the top-right of the expanded panel */}
+        const headerBar = <div className="sidedoc-header" role="banner">
+            <div className="sidedoc-title">{this.props.sideDocsTitle || lf("Docs")}</div>
+            <div className="sidedoc-header-spacer" />
             <sui.Button id="sidedocsclose" className={`sidedocs-close ui icon button`} icon="close" title={lf("Close the side documentation")} ariaLabel={lf("Close the side documentation")} onClick={this.close} />
-            {this.renderTabContent(activeTab, url, builtInDetail, lockedEditor)}
+        </div>;
+
+        const content = <div key="content" id="sidedocsframe-wrapper">
+            {headerBar}
+            <div className="sidedocs-content">
+                {this.renderTabContent(activeTab, url, builtInDetail, lockedEditor)}
+            </div>
         </div>;
 
         const flipNewTabLinkOrder = builtInDetail?.singleTabStop;

From c557124d664bf47fd401d10dd60b71e65bb2ab37 Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Thu, 4 Sep 2025 12:10:33 -0700
Subject: [PATCH 05/16] debounce build v2

---
 cli/cli.ts | 60 +++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 39 insertions(+), 21 deletions(-)

diff --git a/cli/cli.ts b/cli/cli.ts
index b8fbab2998cf..ec0692829eb0 100644
--- a/cli/cli.ts
+++ b/cli/cli.ts
@@ -2810,48 +2810,66 @@ function pxtVersion(): string {
 }
 
 function buildAndWatchAsync(f: () => Promise<string[]>, maxDepth: number): Promise<void> {
-    let currMtime = Date.now()
+    let currMtime = Date.now();
     const DEBOUNCE_MS = 3000;
-    let debounceTimer: any = null;
+    let debounceTimer: NodeJS.Timeout | null = null;
+    let isBuilding = false;
 
     return f()
         .then(dirs => {
             if (globalConfig.noAutoBuild) return
             pxt.debug('watching ' + dirs.join(', ') + '...');
+            
             let loop = () => {
+                // Skip polling if we're currently building or debouncing
+                if (isBuilding || debounceTimer) {
+                    U.nextTick(loop);
+                    return;
+                }
+
                 U.delay(1000)
                     .then(() => maxMTimeAsync(dirs, maxDepth))
                     .then(num => {
                         if (num > currMtime) {
-                            currMtime = num
+                            currMtime = num;
+                            
+                            // Clear any existing debounce timer
                             if (debounceTimer) {
-                                clearTimeout(debounceTimer)
-                                debounceTimer = null
+                                clearTimeout(debounceTimer);
+                                debounceTimer = null;
                             }
 
+                            // Set up debounced build
                             debounceTimer = setTimeout(() => {
-                                debounceTimer = null
+                                debounceTimer = null;
+                                isBuilding = true;
+                                
                                 f()
                                     .then(d => {
-                                        dirs = d
-                                        U.nextTick(loop)
+                                        dirs = d;
+                                        isBuilding = false;
+                                        U.nextTick(loop);
                                     })
                                     .catch((e) => {
-                                        buildFailed("debounced build failed: " + (e && e.message ? e.message : ""), e)
-                                        U.nextTick(loop)
-                                    })
-                            }, DEBOUNCE_MS)
-
-                            // continue polling so subsequent changes reset debounceTimer
-                            U.nextTick(loop)
-                        } else {
-                            U.nextTick(loop)
+                                        buildFailed("debounced build failed: " + (e && e.message ? e.message : ""), e);
+                                        isBuilding = false;
+                                        U.nextTick(loop);
+                                    });
+                            }, DEBOUNCE_MS);
                         }
+                        
+                        // Continue polling regardless of whether we detected changes
+                        U.nextTick(loop);
                     })
-            }
-            U.nextTick(loop)
-        })
-
+                    .catch((e) => {
+                        // Handle maxMTimeAsync errors gracefully
+                        pxt.debug("Error checking file times: " + (e && e.message ? e.message : ""));
+                        U.nextTick(loop);
+                    });
+            };
+            
+            U.nextTick(loop);
+        });
 }
 
 function buildFailed(msg: string, e: any) {

From fab570664a4d6ad09cb2b4b18924bcc1075532f1 Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Thu, 4 Sep 2025 12:16:27 -0700
Subject: [PATCH 06/16] updates to chat component

---
 .../components/controls/Chat/Chat.tsx         |  32 ++-
 .../components/controls/Chat/ChatComposer.tsx |  76 +++--
 .../controls/Chat/ChatErrorBoundary.tsx       |  64 +++++
 .../controls/Chat/chat.serialization.ts       | 116 ++++++--
 .../components/controls/Chat/chat.types.ts    |  24 +-
 react-common/styles/controls/Chat.less        | 175 +++++++++++-
 theme/sidedoc.less                            | 270 ++++++++----------
 webapp/src/container.tsx                      |  17 +-
 8 files changed, 555 insertions(+), 219 deletions(-)
 create mode 100644 react-common/components/controls/Chat/ChatErrorBoundary.tsx

diff --git a/react-common/components/controls/Chat/Chat.tsx b/react-common/components/controls/Chat/Chat.tsx
index 7bd9a19a1088..42da92dd553b 100644
--- a/react-common/components/controls/Chat/Chat.tsx
+++ b/react-common/components/controls/Chat/Chat.tsx
@@ -1,3 +1,5 @@
+/** @format */
+
 import * as React from "react";
 import { classList, ContainerProps } from "../../util";
 import ChatMessageList from "./ChatMessageList";
@@ -20,8 +22,11 @@ export const Chat = (props: ChatProps) => {
     const { id, className, style, messages, onSend, onAppend, registry, tailSize, overscan } = props;
 
     const mergedRegistry = React.useMemo(() => createRegistry(registry), [registry]);
+    const chatId = id || `chat-${Math.random().toString(36).substr(2, 9)}`;
+    const messageListId = `${chatId}-messages`;
+    const composerId = `${chatId}-composer`;
 
-    const handleSend = (text: string) => {
+    const handleSend = React.useCallback((text: string) => {
         // top-level convenience: allow composer to call with text
         const message: Message = {
             id: `${Date.now()}`,
@@ -30,12 +35,29 @@ export const Chat = (props: ChatProps) => {
             timestamp: new Date().toISOString(),
         };
         if (onSend) onSend(message);
-    };
+    }, [onSend]);
 
     return (
-        <div id={id} className={classList("common-chat", className)} style={style}>
-            <ChatMessageList messages={messages} registry={mergedRegistry} onAppend={onAppend} tailSize={tailSize} overscan={overscan} />
-            <ChatComposer onSend={handleSend} />
+        <div
+            id={chatId}
+            className={classList("common-chat", className)}
+            style={style}
+            role="region"
+            aria-label="Chat conversation"
+        >
+            <ChatMessageList
+                id={messageListId}
+                messages={messages}
+                registry={mergedRegistry}
+                onAppend={onAppend}
+                tailSize={tailSize}
+                overscan={overscan}
+            />
+            <ChatComposer
+                id={composerId}
+                onSend={handleSend}
+                aria-describedby={messageListId}
+            />
         </div>
     );
 };
diff --git a/react-common/components/controls/Chat/ChatComposer.tsx b/react-common/components/controls/Chat/ChatComposer.tsx
index b0ab5c6a2b0a..1f1b3b1a8ac6 100644
--- a/react-common/components/controls/Chat/ChatComposer.tsx
+++ b/react-common/components/controls/Chat/ChatComposer.tsx
@@ -1,3 +1,5 @@
+/** @format */
+
 import * as React from "react";
 import { classList, ContainerProps } from "../../util";
 import { Button } from "../Button";
@@ -11,53 +13,75 @@ export interface ChatComposerProps extends ContainerProps {
 }
 
 export const ChatComposer = (props: ChatComposerProps) => {
-    const { onSend, className, style, placeholder, disabled, busy } = props;
+    const { onSend, className, style, placeholder, disabled, busy, id, ...ariaProps } = props;
     const [value, setValue] = React.useState("");
     const textareaRef = React.useRef<HTMLTextAreaElement | null>(null);
+    const resizeTimeoutRef = React.useRef<number>();
 
-    React.useEffect(() => {
-        // auto resize on mount
-        if (textareaRef.current) {
-            textareaRef.current.style.height = "1px";
-            textareaRef.current.style.height = `${textareaRef.current.scrollHeight}px`;
+    const debouncedResize = React.useCallback(() => {
+        if (resizeTimeoutRef.current) {
+            clearTimeout(resizeTimeoutRef.current);
         }
+        resizeTimeoutRef.current = setTimeout(() => {
+            if (!textareaRef.current) return;
+            // Reset height to measure scrollHeight accurately
+            textareaRef.current.style.height = "auto";
+            const newHeight = Math.min(textareaRef.current.scrollHeight, 160); // max ~10rem
+            textareaRef.current.style.height = `${newHeight}px`;
+        }, 16); // ~1 frame at 60fps
     }, []);
 
-    const maybeResize = () => {
-        if (!textareaRef.current) return;
-        textareaRef.current.style.height = "1px";
-        textareaRef.current.style.height = `${textareaRef.current.scrollHeight}px`;
-    };
+    React.useEffect(() => {
+        return () => {
+            if (resizeTimeoutRef.current) {
+                clearTimeout(resizeTimeoutRef.current);
+            }
+        };
+    }, []);
 
-    const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    React.useEffect(() => {
+        // Initial resize
+        debouncedResize();
+    }, [debouncedResize]);
+
+    const handleKeyDown = React.useCallback((e: React.KeyboardEvent<HTMLTextAreaElement>) => {
         if (e.key === "Enter" && !e.shiftKey) {
-            // send
             e.preventDefault();
             const trimmed = value.trim();
-            if (!trimmed) return;
+            if (!trimmed || disabled || busy) return;
             onSend(trimmed);
             setValue("");
+            // Reset height after clearing
+            requestAnimationFrame(() => {
+                if (textareaRef.current) {
+                    textareaRef.current.style.height = "auto";
+                }
+            });
         }
-    };
+    }, [value, onSend, disabled, busy]);
 
-    const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    const handleChange = React.useCallback((e: React.ChangeEvent<HTMLTextAreaElement>) => {
         setValue(e.target.value);
-        maybeResize();
-    };
+        debouncedResize();
+    }, [debouncedResize]);
 
-    const doSend = () => {
+    const doSend = React.useCallback(() => {
         const trimmed = value.trim();
-        if (!trimmed) return;
+        if (!trimmed || disabled || busy) return;
         onSend(trimmed);
         setValue("");
-        if (textareaRef.current) {
-            textareaRef.current.style.height = "1px";
-        }
-    };
+        requestAnimationFrame(() => {
+            if (textareaRef.current) {
+                textareaRef.current.style.height = "auto";
+                textareaRef.current.focus();
+            }
+        });
+    }, [value, onSend, disabled, busy]);
 
     return (
         <div className={classList("common-chat-composer", className)} style={style}>
             <textarea
+                id={id}
                 ref={textareaRef}
                 className={classList("common-textarea", "common-chat-composer-textarea")}
                 placeholder={placeholder || lf("Type a message...")}
@@ -66,6 +90,9 @@ export const ChatComposer = (props: ChatComposerProps) => {
                 onKeyDown={handleKeyDown}
                 aria-label={placeholder || lf("Message input")}
                 disabled={disabled}
+                rows={1}
+                style={{ minHeight: "2.5rem", maxHeight: "10rem", resize: "none", overflow: "hidden" }}
+                {...ariaProps}
             />
             <Button
                 className={classList("common-chat-send-button")}
@@ -73,6 +100,7 @@ export const ChatComposer = (props: ChatComposerProps) => {
                 label={busy ? <div className="common-spinner" /> : lf("Send")}
                 onClick={doSend}
                 disabled={disabled || busy || value.trim().length === 0}
+                aria-keyshortcuts="Enter"
             />
         </div>
     );
diff --git a/react-common/components/controls/Chat/ChatErrorBoundary.tsx b/react-common/components/controls/Chat/ChatErrorBoundary.tsx
new file mode 100644
index 000000000000..4236ec45e573
--- /dev/null
+++ b/react-common/components/controls/Chat/ChatErrorBoundary.tsx
@@ -0,0 +1,64 @@
+/** @format */
+
+import * as React from "react";
+import { classList } from "../../util";
+
+interface ChatErrorBoundaryProps {
+    children: React.ReactNode;
+    fallback?: React.ComponentType<{ error?: Error; reset?: () => void }>;
+}
+
+interface ChatErrorBoundaryState {
+    hasError: boolean;
+    error?: Error;
+}
+
+export class ChatErrorBoundary extends React.Component<ChatErrorBoundaryProps, ChatErrorBoundaryState> {
+    constructor(props: ChatErrorBoundaryProps) {
+        super(props);
+        this.state = { hasError: false };
+    }
+
+    static getDerivedStateFromError(error: Error): ChatErrorBoundaryState {
+        return { hasError: true, error };
+    }
+
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+        console.error('Chat component error:', error, errorInfo);
+    }
+
+    handleReset = () => {
+        this.setState({ hasError: false, error: undefined });
+    }
+
+    render() {
+        if (this.state.hasError) {
+            if (this.props.fallback) {
+                const Fallback = this.props.fallback;
+                return <Fallback error={this.state.error} reset={this.handleReset} />;
+            }
+
+            return (
+                <div className={classList("common-chat-error")}>
+                    <div className="common-chat-error-content">
+                        <div className="common-chat-error-icon">⚠️</div>
+                        <div className="common-chat-error-message">
+                            Chat temporarily unavailable
+                        </div>
+                        <button
+                            className="common-button"
+                            onClick={this.handleReset}
+                            aria-label="Retry chat component"
+                        >
+                            Retry
+                        </button>
+                    </div>
+                </div>
+            );
+        }
+
+        return this.props.children;
+    }
+}
+
+export default ChatErrorBoundary;
diff --git a/react-common/components/controls/Chat/chat.serialization.ts b/react-common/components/controls/Chat/chat.serialization.ts
index 1d857033d448..70ddc60514ec 100644
--- a/react-common/components/controls/Chat/chat.serialization.ts
+++ b/react-common/components/controls/Chat/chat.serialization.ts
@@ -1,44 +1,118 @@
-import { ChatEnvelope, Message, AttachmentManifest, CHAT_SCHEMA_VERSION } from "./chat.types";
+/** @format */
+
+import {
+    ChatEnvelope,
+    Message,
+    AttachmentManifest,
+    CHAT_SCHEMA_VERSION,
+    isValidMessage,
+    sanitizeMessage,
+} from "./chat.types";
+
+export interface SerializationOptions {
+    validateMessages?: boolean;
+    sanitizeMessages?: boolean;
+}
+
+export function exportEnvelope(
+    messages: Message[],
+    attachments?: AttachmentManifest,
+    options: SerializationOptions = { validateMessages: true, sanitizeMessages: true }
+): ChatEnvelope {
+    let processedMessages = messages;
+
+    if (options.validateMessages || options.sanitizeMessages) {
+        processedMessages = messages
+            .filter((m) => (options.validateMessages ? isValidMessage(m) : true))
+            .map((m) => (options.sanitizeMessages ? sanitizeMessage(m) : m));
+    }
 
-export function exportEnvelope(messages: Message[], attachments?: AttachmentManifest): ChatEnvelope {
     // Ensure a minimal, serializable copy (no functions/JSX)
-    const safeMessages = messages.map((m) => ({ ...m, parts: m.parts.map((p) => ({ ...p })) }));
+    const safeMessages = processedMessages.map((m) => ({
+        ...m,
+        parts: m.parts.map((p) => ({ ...p })),
+    }));
+
     return {
         schemaVersion: CHAT_SCHEMA_VERSION,
         exportedAt: new Date().toISOString(),
         messages: safeMessages,
-        attachments,
+        attachments: attachments ? { ...attachments } : undefined,
     };
 }
 
-export function exportEnvelopeToJson(messages: Message[], attachments?: AttachmentManifest): string {
-    return JSON.stringify(exportEnvelope(messages, attachments));
+export function exportEnvelopeToJson(
+    messages: Message[],
+    attachments?: AttachmentManifest,
+    options?: SerializationOptions
+): string {
+    try {
+        return JSON.stringify(exportEnvelope(messages, attachments, options));
+    } catch (error) {
+        throw new Error(`Failed to serialize chat envelope: ${error instanceof Error ? error.message : String(error)}`);
+    }
 }
 
 export function importEnvelope(raw: string | any): ChatEnvelope {
     let obj: any;
-    if (typeof raw === "string") {
-        obj = JSON.parse(raw);
-    } else {
-        obj = raw;
+
+    try {
+        if (typeof raw === "string") {
+            obj = JSON.parse(raw);
+        } else {
+            obj = raw;
+        }
+    } catch (error) {
+        throw new Error(`Invalid JSON in chat envelope: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    if (!obj || typeof obj !== "object") {
+        throw new Error("Invalid envelope: not an object");
     }
 
-    if (!obj || typeof obj !== "object") throw new Error("Invalid envelope: not an object");
-    const schemaVersion = obj.schemaVersion || 0;
+    const schemaVersion = Number(obj.schemaVersion) || 0;
     if (schemaVersion !== CHAT_SCHEMA_VERSION) {
-        // TODO: Add migration here
+        // TODO: Add migration logic here
+        console.warn(`Unsupported envelope schemaVersion: ${schemaVersion}, expected: ${CHAT_SCHEMA_VERSION}`);
         throw new Error(`Unsupported envelope schemaVersion: ${schemaVersion}`);
     }
 
-    const messages: Message[] = (obj.messages || []).map((m: any) => ({
-        id: m.id,
-        parts: (m.parts || []).map((p: any) => ({ ...p })),
-        author: m.author,
-        timestamp: m.timestamp,
-        metadata: m.metadata,
-    }));
+    if (!Array.isArray(obj.messages)) {
+        throw new Error("Invalid envelope: messages must be an array");
+    }
+
+    const messages: Message[] = obj.messages.map((m: any, index: number) => {
+        if (!m || typeof m !== "object") {
+            throw new Error(`Invalid message at index ${index}: not an object`);
+        }
+
+        if (!m.id || typeof m.id !== "string") {
+            throw new Error(`Invalid message at index ${index}: missing or invalid id`);
+        }
+
+        if (!Array.isArray(m.parts)) {
+            throw new Error(`Invalid message at index ${index}: parts must be an array`);
+        }
+
+        return {
+            id: String(m.id),
+            parts: m.parts.map((p: any, partIndex: number) => {
+                if (!p || typeof p !== "object") {
+                    throw new Error(`Invalid part at message ${index}, part ${partIndex}: not an object`);
+                }
+                if (!p.kind || typeof p.kind !== "string") {
+                    throw new Error(`Invalid part at message ${index}, part ${partIndex}: missing or invalid kind`);
+                }
+                return { ...p };
+            }),
+            author: m.author ? String(m.author) : undefined,
+            timestamp: m.timestamp ? String(m.timestamp) : undefined,
+            metadata: m.metadata,
+        };
+    });
 
-    const attachments: AttachmentManifest | undefined = obj.attachments;
+    const attachments: AttachmentManifest | undefined =
+        obj.attachments && typeof obj.attachments === "object" ? obj.attachments : undefined;
 
     return {
         schemaVersion,
diff --git a/react-common/components/controls/Chat/chat.types.ts b/react-common/components/controls/Chat/chat.types.ts
index cd705e48a188..a544566f29bf 100644
--- a/react-common/components/controls/Chat/chat.types.ts
+++ b/react-common/components/controls/Chat/chat.types.ts
@@ -1,3 +1,5 @@
+/** @format */
+
 // Chat public types and serialization envelope
 
 export const CHAT_SCHEMA_VERSION = 1;
@@ -8,8 +10,7 @@ export type PartKind = string;
 export interface MessagePartBase {
     kind: string; // semantic kind name
     version?: number; // part schema version
-    // any additional serializable fields are allowed
-    [k: string]: any;
+    [k: string]: string | number | boolean | null | undefined | object; // Restrict to serializable values only
 }
 
 export interface TextPart extends MessagePartBase {
@@ -65,3 +66,22 @@ export function cloneMessageWithId(message: Message, newId: string): Message {
         parts: message.parts.map((p) => ({ ...p })),
     };
 }
+
+// Validation helpers
+export function isValidMessage(obj: any): obj is Message {
+    return obj && typeof obj.id === "string" && Array.isArray(obj.parts) && obj.parts.every(isValidMessagePart);
+}
+
+export function isValidMessagePart(obj: any): obj is MessagePart {
+    return obj && typeof obj.kind === "string" && (obj.version === undefined || typeof obj.version === "number");
+}
+
+export function sanitizeMessage(message: Message): Message {
+    return {
+        ...message,
+        id: String(message.id),
+        parts: message.parts.filter(isValidMessagePart),
+        author: message.author ? String(message.author) : undefined,
+        timestamp: message.timestamp ? String(message.timestamp) : undefined,
+    };
+}
diff --git a/react-common/styles/controls/Chat.less b/react-common/styles/controls/Chat.less
index 40464efca10b..ac470305c3eb 100644
--- a/react-common/styles/controls/Chat.less
+++ b/react-common/styles/controls/Chat.less
@@ -10,6 +10,7 @@
     border-radius: 0.5rem;
     border: 1px solid var(--pxt-neutral-stencil1);
     overflow: hidden;
+    position: relative;
 }
 
 .common-chat-message-list {
@@ -19,12 +20,29 @@
     display: flex;
     flex-direction: column;
     gap: 0.5rem;
+    scroll-behavior: smooth;
+    /* Ensure proper scrolling on mobile */
+    -webkit-overflow-scrolling: touch;
 }
 
 .common-chat-message {
     display: flex;
     flex-direction: column;
     max-width: 100%;
+    opacity: 0;
+    animation: messageSlideIn 0.3s ease-out forwards;
+}
+
+@keyframes messageSlideIn {
+    from {
+        opacity: 0;
+        transform: translateY(8px);
+    }
+
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
 }
 
 .common-chat-message.from-user {
@@ -41,17 +59,19 @@
     gap: 0.5rem;
     font-size: 0.75rem;
     color: var(--pxt-neutral-foreground3);
+    margin-bottom: 0.25rem;
 }
 
 .common-chat-message-body {
     display: flex;
     flex-direction: column;
     gap: 0.25rem;
-    margin-top: 0.25rem;
 }
 
 .common-chat-message-part {
-    max-width: 72%;
+    max-width: min(72%, 28rem);
+    word-wrap: break-word;
+    overflow-wrap: break-word;
 }
 
 .common-chat-part-text {
@@ -59,14 +79,38 @@
     color: var(--pxt-neutral-foreground1);
     padding: 0.6rem 0.75rem;
     border-radius: 0.5rem;
-    box-shadow: 0 1px 0 rgba(0,0,0,0.02);
+    box-shadow: 0 1px 0 rgba(0, 0, 0, 0.02);
     white-space: pre-wrap;
+    line-height: 1.4;
+
+    /* Improve text selection */
+    user-select: text;
+    -webkit-user-select: text;
+    -moz-user-select: text;
+    -ms-user-select: text;
 }
 
 .common-chat-part-image {
     max-width: 18rem;
     border-radius: 0.35rem;
     border: 1px solid var(--pxt-neutral-stencil1);
+    transition: opacity 0.2s ease;
+}
+
+.common-chat-part-image:not([src]),
+.common-chat-part-image[src=""] {
+    opacity: 0.5;
+    background-color: var(--pxt-neutral-background1);
+    min-height: 2rem;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.common-chat-part-image::before {
+    content: "🖼️ Loading...";
+    color: var(--pxt-neutral-foreground3);
+    font-size: 0.875rem;
 }
 
 .common-chat-composer {
@@ -75,6 +119,7 @@
     padding: 0.5rem;
     border-top: 1px solid var(--pxt-neutral-stencil1);
     background-color: var(--pxt-neutral-background1);
+    align-items: flex-end;
 }
 
 .common-chat-composer-textarea {
@@ -82,14 +127,37 @@
     min-height: 2.5rem;
     max-height: 10rem;
     resize: none;
-    padding: 0.5rem;
-    border-radius: 0.25rem;
+    padding: 0.75rem;
+    border-radius: 0.5rem;
     border: 1px solid var(--pxt-neutral-stencil1);
     font-family: var(--page-font, "Segoe UI", Tahoma, Geneva, Verdana);
+    font-size: 0.875rem;
+    line-height: 1.4;
+    transition: border-color 0.2s ease, box-shadow 0.2s ease;
+
+    /* Improve focus state */
+    &:focus {
+        outline: none;
+        border-color: var(--pxt-primary-background);
+        box-shadow: 0 0 0 2px var(--pxt-primary-background-transparent);
+    }
+
+    &:disabled {
+        opacity: 0.6;
+        background-color: var(--pxt-neutral-background2);
+        cursor: not-allowed;
+    }
 }
 
 .common-chat-send-button {
     align-self: flex-end;
+    min-height: 2.5rem;
+    transition: all 0.2s ease;
+
+    &:disabled {
+        opacity: 0.5;
+        cursor: not-allowed;
+    }
 }
 
 .common-chat-part-fallback {
@@ -98,13 +166,58 @@
     padding: 0.5rem;
     border-radius: 0.3rem;
     border: 1px dashed var(--pxt-neutral-stencil1);
-    font-family: var(--page-font, "Segoe UI", Tahoma, Geneva, Verdana);
+    font-family: monospace;
+    font-size: 0.75rem;
+    white-space: pre-wrap;
+    max-width: 20rem;
+    max-height: 10rem;
+    overflow: auto;
 }
 
 .common-chat-demo-card {
     display: flex;
     flex-direction: column;
     gap: 0.5rem;
+    padding: 0.75rem;
+    background: var(--pxt-neutral-background1);
+    border: 1px solid var(--pxt-neutral-stencil1);
+    border-radius: 0.5rem;
+    min-width: 12rem;
+}
+
+/* Error boundary styles */
+.common-chat-error {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 2rem;
+    text-align: center;
+    background-color: var(--pxt-neutral-background2);
+    border-radius: 0.5rem;
+    border: 1px solid var(--pxt-danger-background);
+}
+
+.common-chat-error-content {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 1rem;
+    max-width: 20rem;
+}
+
+.common-chat-error-icon {
+    font-size: 2rem;
+}
+
+.common-chat-error-message {
+    color: var(--pxt-neutral-foreground2);
+    font-weight: 500;
+}
+
+/* Loading state */
+.common-chat.loading {
+    opacity: 0.7;
+    pointer-events: none;
 }
 
 /* small scroll to bottom helper */
@@ -112,11 +225,59 @@
     position: absolute;
     right: 1rem;
     bottom: 4.25rem;
+    background: var(--pxt-primary-background);
+    color: var(--pxt-primary-foreground);
+    border: none;
+    border-radius: 50%;
+    width: 2.5rem;
+    height: 2.5rem;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+    transition: all 0.2s ease;
+
+    &:hover {
+        transform: translateY(-1px);
+        box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+    }
+}
+
+/* High contrast mode support */
+@media (prefers-contrast: high) {
+    .common-chat-part-text {
+        border: 1px solid var(--pxt-neutral-foreground2);
+    }
+
+    .common-chat-composer-textarea:focus {
+        border-width: 2px;
+    }
 }
 
 /* Respect reduced-motion */
 @media (prefers-reduced-motion: reduce) {
-    .common-chat-message-body {
+    .common-chat-message {
+        animation: none !important;
+        opacity: 1;
+    }
+
+    .common-chat-message-list {
+        scroll-behavior: auto;
+    }
+
+    * {
         transition: none !important;
     }
 }
+
+/* Dark theme optimizations */
+@media (prefers-color-scheme: dark) {
+    .common-chat {
+        box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.05);
+    }
+
+    .common-chat-part-text {
+        box-shadow: 0 1px 0 rgba(255, 255, 255, 0.05);
+    }
+}
\ No newline at end of file
diff --git a/theme/sidedoc.less b/theme/sidedoc.less
index 773419bd3e2e..95ee22fc8afa 100644
--- a/theme/sidedoc.less
+++ b/theme/sidedoc.less
@@ -12,19 +12,15 @@
 /* Side Docs layout */
 #sidedocs {
     top: 0;
+    right: 0;
+    width: 0;
     z-index: @sidedocZIndex;
     visibility: hidden;
     opacity: 0;
-    right: 0;
-    width: 0;
     /* Animate width/right/opacity so the side panel transitions with the same timing as the tabs */
     transition: width 0.25s ease, right 0.25s ease, opacity 0.25s ease;
 }
 
-code.hljs {
-    background: none;
-}
-
 #sidedocsbar {
     position: absolute;
     right: 1rem;
@@ -37,60 +33,62 @@ code.hljs {
     background: white;
 }
 
-/* Close button inside the SideDocs panel (top-right) */
-#sidedocsframe-wrapper .sidedocs-close {
-    z-index: @sidedocZIndex + 2;
-    background: transparent;
-    border: none;
-    color: var(--pxt-neutral-foreground1);
-    padding: 0.25rem;
-    line-height: 1;
-}
-
-#sidedocsframe-wrapper .sidedocs-close:hover,
-#sidedocsframe-wrapper .sidedocs-close:focus {
+code.hljs {
+    background: none;
 }
 
-.sideDocs #sidedocs {
-    position: fixed;
-    visibility: visible;
-    opacity: 1;
-    width: var(--sidedocWidth);
-    /* Don't let the panel expand beyond a fraction of the viewport */
-    max-width: 50vw;
-    top: calc(@mainMenuHeight + 1rem);
-    height: ~"calc(100% - @{mainMenuHeight} - @{editorToolsCollapsedHeight} - 2rem)";
-}
+/* Side docs - expanded state */
+.sideDocs {
+    /* Define the clamped width value for use by the panel and the tabstrip */
+    --sidedocWidth:~"min(@{sideBarWidth}, 50vw)";
 
-.sideDocs #sidedocsframe-wrapper {
-    display: flex;
-    flex-direction: column;
-    position: relative;
-    overflow: hidden;
-    width: var(--sidedocWidth);
-    height: 100%;
-    -webkit-box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
-    -moz-box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
-    box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
-    border-top-left-radius: 5px;
-    border-bottom-left-radius: 5px;
-    z-index: @sidedocZIndex;
+    #sidedocs {
+        position: fixed;
+        visibility: visible;
+        opacity: 1;
+        width: var(--sidedocWidth);
+        /* Don't let the panel expand beyond a fraction of the viewport */
+        max-width: 50vw;
+        top: calc(@mainMenuHeight + 1rem);
+        height:~"calc(100% - @{mainMenuHeight} - @{editorToolsCollapsedHeight} - 2rem)";
+    }
 
-    &:has(aside:focus-visible) {
-        outline: @editorFocusBorderSize solid var(--pxt-focus-border);
+    #sidedocsframe-wrapper {
+        display: flex;
+        flex-direction: column;
+        position: relative;
+        overflow: hidden;
+        width: var(--sidedocWidth);
+        height: 100%;
+        -webkit-box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
+        -moz-box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
+        box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
+        border-top-left-radius: 5px;
+        border-bottom-left-radius: 5px;
+        z-index: @sidedocZIndex;
+
+        &:has(aside:focus-visible) {
+            outline: @editorFocusBorderSize solid var(--pxt-focus-border);
+        }
     }
-}
 
-.sideDocs #sidedocsframe {
-    width: 100%;
-    height: 100%;
-}
+    #sidedocsframe {
+        width: 100%;
+        height: 100%;
+        border: none;
+        background: white;
+    }
 
-/* The old sidedocstoggle control was removed; the new close button is inside #sidedocsframe-wrapper */
+    #sidedocsbar {
+        top: 1rem;
+        z-index: @sidedocZIndex+1;
+    }
 
-.sideDocs #sidedocsbar {
-    top: 1rem;
-    z-index: @sidedocZIndex+1;
+    /* Move the tab strip to the panel edge when sidebar is open */
+    #sidedocstabs {
+        right: var(--sidedocWidth);
+        transition: right 0.25s ease;
+    }
 }
 
 #sidedocsbar .ui.link .icon {
@@ -109,45 +107,6 @@ code.hljs {
     #sidedocsframe-wrapper {
         width: 100% !important;
     }
-
-    /* The old sidedocstoggle control was removed; the new close button is inside #sidedocsframe-wrapper */
-}
-
-/* Large Monitor */
-@media only screen and (min-width: @largeMonitorBreakpoint) {
-    /* override the CSS variable used by the panel and tabs */
-    .sideDocs {
-        --sidedocWidth: ~"min(@{sideBarWidthLarge}, 50vw)";
-    }
-    /* The old sidedocstoggle control was removed; the new close button is inside #sidedocsframe-wrapper */
-}
-
-/* Small Monitor */
-@media only screen and (min-width: @computerBreakpoint) and (max-width: @largestSmallMonitor) {
-}
-
-/* Tablet */
-@media only screen and (min-width: @tabletBreakpoint) and (max-width: @largestTabletScreen) {
-}
-
-/* Mobile */
-@media only screen and (max-width: @largestMobileScreen) {
-    /* override the CSS variable used by the panel and tabs on mobile */
-    .sideDocs {
-        --sidedocWidth: ~"min(@{sideBarWidthSmall}, 50vw)";
-    }
-    /* The old sidedocstoggle control was removed; the new close button is inside #sidedocsframe-wrapper */
-    /* position the tabstrip appropriately on mobile */
-    #sidedocstabs,
-    .sidedoc-tablist {
-        top: calc(@mobileMenuHeight + 8px);
-    }
-}
-
-@media only screen and (max-height: @tallEditorBreakpoint) and (min-width: @largestMobileScreen) {
-    .sideDocs #sidedocs {
-        top: calc(@thinMenuHeight + 1rem);
-    }
 }
 
 /* Side docs tab strip styles */
@@ -165,18 +124,6 @@ code.hljs {
     transition: none;
 }
 
-/* When the sidebar is open, define the clamped width value for use by the panel and the tabstrip */
-.sideDocs {
-    --sidedocWidth: ~"min(@{sideBarWidth}, 50vw)";
-}
-
-/* When the sidebar is open (body .sideDocs), move the tab strip to the panel edge */
-.sideDocs #sidedocstabs {
-    /* place the tab strip at the same clamped width used by the panel */
-    right: var(--sidedocWidth);
-    transition: right 0.25s ease;
-}
-
 .sidedoc-tab {
     width: 2.5rem;
     height: 2.5rem;
@@ -188,65 +135,86 @@ code.hljs {
     color: var(--pxt-neutral-foreground1);
     cursor: pointer;
     border: 1px solid transparent;
-}
 
-.sidedoc-tab.active {
-    background: var(--pxt-neutral-alpha20);
-    border-color: var(--pxt-secondary-accent);
-}
+    &.active {
+        background: var(--pxt-neutral-alpha20);
+        border-color: var(--pxt-secondary-accent);
+    }
 
-/* Make the inner button fill the tab wrapper */
-.sidedoc-tab .ui.button {
-    width: 100%;
-    height: 100%;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    background: transparent;
-    border: none;
-    padding: 0;
-    margin: 0;
-    box-shadow: none;
+    /* Make the inner button fill the tab wrapper */
+    .ui.button {
+        width: 100%;
+        height: 100%;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        background: transparent;
+        border: none;
+        padding: 0;
+        margin: 0;
+        box-shadow: none;
+    }
 }
 
-#sidedocsframe-wrapper .sidedoc-header {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    padding: 0.25rem;
-    background: var(--pxt-header-background);
-    color: var(--pxt-primary-foreground);
-    z-index: @sidedocZIndex + 3;
-    min-height: fit-content;
+/* Header and content area styles */
+#sidedocsframe-wrapper {
+    .sidedoc-header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 0.25rem;
+        background: var(--pxt-header-background);
+        color: var(--pxt-primary-foreground);
+        z-index: @sidedocZIndex + 3;
+        min-height: fit-content;
+
+        .sidedoc-header-spacer {
+            flex-grow: 1;
+        }
+    }
+
+    .sidedoc-title {
+        font-weight: 600;
+        font-size: 1rem;
+        line-height: 1;
+        margin: 0;
+    }
 
-    .sidedoc-header-spacer {
+    /* content area below header */
+    .sidedocs-content {
         flex-grow: 1;
+        display: flex;
+        flex-direction: column;
+        min-height: 0;
+
+        /* iframe inside content area should flex to fill available space */
+        #sidedocsframe {
+            flex: 1;
+            min-height: 0;
+        }
     }
 }
 
-#sidedocsframe-wrapper .sidedoc-title {
-    font-weight: 600;
-    font-size: 1rem;
-    line-height: 1;
-    margin: 0;
+/* Media Queries */
+@media only screen and (min-width: @largeMonitorBreakpoint) {
+    .sideDocs {
+        --sidedocWidth:~"min(@{sideBarWidthLarge}, 50vw)";
+    }
 }
 
-/* close button in header */
-#sidedocsframe-wrapper .sidedocs-close {
-    background: transparent;
-    border: none;
-    color: var(--pxt-neutral-foreground1);
-    opacity: 0.95;
-}
+@media only screen and (max-width: @largestMobileScreen) {
+    .sideDocs {
+        --sidedocWidth:~"min(@{sideBarWidthSmall}, 50vw)";
+    }
 
-#sidedocsframe-wrapper .sidedocs-close:hover,
-#sidedocsframe-wrapper .sidedocs-close:focus {
-    opacity: 1;
+    #sidedocstabs,
+    .sidedoc-tablist {
+        top: calc(@mobileMenuHeight + 8px);
+    }
 }
 
-/* content area below header */
-#sidedocsframe-wrapper .sidedocs-content {
-    flex-grow: 1;
-    overflow: auto;
-    -webkit-overflow-scrolling: touch;
-}
+@media only screen and (max-height: @tallEditorBreakpoint) and (min-width: @largestMobileScreen) {
+    .sideDocs #sidedocs {
+        top: calc(@thinMenuHeight + 1rem);
+    }
+}
\ No newline at end of file
diff --git a/webapp/src/container.tsx b/webapp/src/container.tsx
index 1322f9052717..b77e4624dea8 100644
--- a/webapp/src/container.tsx
+++ b/webapp/src/container.tsx
@@ -1106,16 +1106,16 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             tabIndex: 0,
         };
 
-        const openInNewTab = !lockedEditor && <div key="newTab" className="ui app hide" id="sidedocsbar">
-            <a className="ui icon link" aria-label={lf("Open documentation in new tab")} {...openInNewTabLinkProps}>
-                <sui.Icon icon="external" />
-            </a>
-        </div>;
+        const openInNewTab = !lockedEditor && <a className="ui icon link sidedocs-opentab" aria-label={lf("Open documentation in new tab")} {...openInNewTabLinkProps}>
+            <sui.Icon icon="external" />
+        </a>;
 
         const headerBar = <div className="sidedoc-header" role="banner">
             <div className="sidedoc-title">{this.props.sideDocsTitle || lf("Docs")}</div>
-            <div className="sidedoc-header-spacer" />
-            <sui.Button id="sidedocsclose" className={`sidedocs-close ui icon button`} icon="close" title={lf("Close the side documentation")} ariaLabel={lf("Close the side documentation")} onClick={this.close} />
+            <div className="sidedoc-controls">
+                {openInNewTab}
+                <sui.Button id="sidedocsclose" className={`sidedocs-close ui icon button`} icon="close" title={lf("Close the side documentation")} ariaLabel={lf("Close the side documentation")} onClick={this.close} />
+            </div>
         </div>;
 
         const content = <div key="content" id="sidedocsframe-wrapper">
@@ -1125,8 +1125,7 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             </div>
         </div>;
 
-        const flipNewTabLinkOrder = builtInDetail?.singleTabStop;
-        const contentParts = flipNewTabLinkOrder ? [content, openInNewTab] : [openInNewTab, content];
+        const contentParts = [content];
 
         /* eslint-disable @microsoft/sdl/react-iframe-missing-sandbox */
         return <div>

From 5c328662846166265fcec6fc57b2cfab5c5b6326 Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Thu, 4 Sep 2025 13:10:08 -0700
Subject: [PATCH 07/16] chat fix

---
 react-common/styles/controls/Chat.less | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/react-common/styles/controls/Chat.less b/react-common/styles/controls/Chat.less
index ac470305c3eb..35127df8e9e9 100644
--- a/react-common/styles/controls/Chat.less
+++ b/react-common/styles/controls/Chat.less
@@ -69,7 +69,7 @@
 }
 
 .common-chat-message-part {
-    max-width: min(72%, 28rem);
+    max-width: ~"min(72%, 28rem)";
     word-wrap: break-word;
     overflow-wrap: break-word;
 }

From a519da73d7fae6c6676ae89ce65fd97011c62bbb Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Thu, 4 Sep 2025 17:25:15 -0700
Subject: [PATCH 08/16] make sidedocs resizable

---
 theme/sidedoc.less       |  92 ++++++++++++++++++-
 webapp/src/container.tsx | 193 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 276 insertions(+), 9 deletions(-)

diff --git a/theme/sidedoc.less b/theme/sidedoc.less
index 95ee22fc8afa..7e63912bad33 100644
--- a/theme/sidedoc.less
+++ b/theme/sidedoc.less
@@ -39,16 +39,20 @@ code.hljs {
 
 /* Side docs - expanded state */
 .sideDocs {
-    /* Define the clamped width value for use by the panel and the tabstrip */
+    /* Define the default width value for use by the panel and the tabstrip */
     --sidedocWidth:~"min(@{sideBarWidth}, 50vw)";
 
+    /* Use user-set width (in vw) if available, otherwise use default */
+    --effectiveWidth: var(--sidedoc-user-width, var(--sidedocWidth));
+
     #sidedocs {
         position: fixed;
         visibility: visible;
         opacity: 1;
-        width: var(--sidedocWidth);
+        width: var(--effectiveWidth);
         /* Don't let the panel expand beyond a fraction of the viewport */
-        max-width: 50vw;
+        max-width: 60vw;
+        min-width: 20vw;
         top: calc(@mainMenuHeight + 1rem);
         height:~"calc(100% - @{mainMenuHeight} - @{editorToolsCollapsedHeight} - 2rem)";
     }
@@ -58,7 +62,7 @@ code.hljs {
         flex-direction: column;
         position: relative;
         overflow: hidden;
-        width: var(--sidedocWidth);
+        width: var(--effectiveWidth);
         height: 100%;
         -webkit-box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
         -moz-box-shadow: 0px 0px 20px 0px rgba(0, 0, 0, 0.41);
@@ -86,7 +90,7 @@ code.hljs {
 
     /* Move the tab strip to the panel edge when sidebar is open */
     #sidedocstabs {
-        right: var(--sidedocWidth);
+        right: var(--effectiveWidth);
         transition: right 0.25s ease;
     }
 }
@@ -195,16 +199,94 @@ code.hljs {
     }
 }
 
+/* Resize handle styles */
+.sidedocs-resize-handle {
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: 4px;
+    height: 100%;
+    cursor: ew-resize;
+    background: transparent;
+    z-index: @sidedocZIndex + 2;
+
+    /* Extended hit area for easier interaction */
+    &::before {
+        content: '';
+        position: absolute;
+        left: -2px;
+        top: 0;
+        width: 8px;
+        height: 100%;
+    }
+
+    /* Visible indicator on hover/focus */
+    &:hover,
+    &:focus,
+    &.resizing {
+        background: var(--pxt-secondary-accent);
+        outline: none;
+    }
+
+    &:focus-visible {
+        outline: 2px solid var(--pxt-focus-border);
+        outline-offset: 2px;
+    }
+
+    /* Hide on mobile to avoid accidental touches */
+    @media only screen and (max-width: @largestMobileScreen) {
+        display: none;
+    }
+}
+
+/* Body cursor changes during resize */
+body.resizing-sidedocs {
+    cursor: ew-resize !important;
+    user-select: none !important;
+    
+    /* Disable transitions during resize for immediate feedback */
+    #sidedocs,
+    #sidedocsframe-wrapper {
+        transition: none !important;
+    }
+}
+
+/* High contrast support */
+@media (prefers-contrast: high) {
+    .sidedocs-resize-handle {
+        &:hover,
+        &:focus-visible,
+        &.resizing,
+        &:active {
+            background: CanvasText;
+        }
+    }
+}
+
+/* Reduced motion support */
+@media (prefers-reduced-motion: reduce) {
+    .sidedocs-resize-handle {
+        transition: none;
+    }
+}
+
 /* Media Queries */
 @media only screen and (min-width: @largeMonitorBreakpoint) {
     .sideDocs {
         --sidedocWidth:~"min(@{sideBarWidthLarge}, 50vw)";
+        --effectiveWidth: var(--sidedoc-user-width, var(--sidedocWidth));
     }
 }
 
 @media only screen and (max-width: @largestMobileScreen) {
     .sideDocs {
         --sidedocWidth:~"min(@{sideBarWidthSmall}, 50vw)";
+        --effectiveWidth: var(--sidedoc-user-width, var(--sidedocWidth));
+
+        /* Disable resize on small screens */
+        .sidedocs-resize-handle {
+            display: none;
+        }
     }
 
     #sidedocstabs,
diff --git a/webapp/src/container.tsx b/webapp/src/container.tsx
index b77e4624dea8..3af11651d6d5 100644
--- a/webapp/src/container.tsx
+++ b/webapp/src/container.tsx
@@ -816,6 +816,9 @@ export interface SideDocsState {
     activeTabId?: string;
     sideDocsWidthPx?: number;
     tabsTopPx?: number;
+    // Resize-related state
+    isResizing?: boolean;
+    sideDocsUserWidthPercent?: number; // User-set width as percentage of viewport
 }
 
 
@@ -837,6 +840,7 @@ export const builtInPrefix = "/builtin/"
 
 export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
     private openingSideDoc = false;
+    private resizeHandleRef = React.createRef<HTMLDivElement>();
 
     constructor(props: SideDocsProps) {
         super(props);
@@ -845,13 +849,17 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             sideDocsCollapsed: undefined,
             activeTabId: 'docs-iframe',
             sideDocsWidthPx: 0,
-            tabsTopPx: 48
+            tabsTopPx: 48,
+            isResizing: false,
+            sideDocsUserWidthPercent: undefined
         }
 
         this.toggleVisibility = this.toggleVisibility.bind(this);
         this.notifyPopOut = this.notifyPopOut.bind(this);
         this.close = this.close.bind(this);
         this.updateLayoutMeasurements = this.updateLayoutMeasurements.bind(this);
+        this.handleResizeStart = this.handleResizeStart.bind(this);
+        this.handleResizeKeyDown = this.handleResizeKeyDown.bind(this);
     }
 
     private rootDocsUrl(): string {
@@ -958,10 +966,22 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
     componentDidMount() {
         window.addEventListener('resize', this.updateLayoutMeasurements);
         this.updateLayoutMeasurements();
+        
+        // Load saved width preference
+        const savedWidthPercent = pxt.storage.getLocal("sidedocs-width-percent");
+        if (savedWidthPercent) {
+            const widthPercent = parseFloat(savedWidthPercent);
+            if (!isNaN(widthPercent) && widthPercent >= 20 && widthPercent <= 60) {
+                this.setState({ sideDocsUserWidthPercent: widthPercent });
+                const root = document.documentElement;
+                root.style.setProperty('--sidedoc-user-width', `${widthPercent}vw`);
+            }
+        }
     }
 
     componentWillUnmount() {
         window.removeEventListener('resize', this.updateLayoutMeasurements);
+        document.body.classList.remove('resizing-sidedocs');
     }
 
     componentDidUpdate() {
@@ -974,6 +994,12 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         }
 
         this.updateLayoutMeasurements();
+        
+        // Apply user-set width if available
+        if (this.state.sideDocsUserWidthPercent) {
+            const root = document.documentElement;
+            root.style.setProperty('--sidedoc-user-width', `${this.state.sideDocsUserWidthPercent}vw`);
+        }
     }
 
     UNSAFE_componentWillReceiveProps(nextProps: SideDocsProps) {
@@ -1000,7 +1026,9 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             || this.state.docsIframeUrl != nextState.docsIframeUrl
             || this.state.activeTabId != nextState.activeTabId
             || this.state.sideDocsWidthPx != nextState.sideDocsWidthPx
-            || this.state.tabsTopPx != nextState.tabsTopPx;
+            || this.state.tabsTopPx != nextState.tabsTopPx
+            || this.state.isResizing != nextState.isResizing
+            || this.state.sideDocsUserWidthPercent != nextState.sideDocsUserWidthPercent;
     }
 
     private handleKeyDown = (ev: React.KeyboardEvent<HTMLElement>) => {
@@ -1078,17 +1106,157 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             newState.tabsTopPx = 48;
         }
         if (newState.sideDocsWidthPx !== this.state.sideDocsWidthPx || newState.tabsTopPx !== this.state.tabsTopPx) {
+            // Don't update state during resize to prevent DOM interference
+            if (this.state.isResizing) {
+                return;
+            }
             this.setState(newState as SideDocsState);
         }
     }
 
+    private handleResizeStart(e: React.MouseEvent | React.TouchEvent | React.PointerEvent) {
+        e.preventDefault();
+        e.stopPropagation();
+        
+        if (this.state.isResizing) {
+            return;
+        }
+        
+        // Capture pointer events to ensure we get all mouse movements
+        const target = e.currentTarget as HTMLElement;
+        if ('pointerId' in e.nativeEvent && 'setPointerCapture' in target) {
+            target.setPointerCapture((e.nativeEvent as PointerEvent).pointerId);
+        }
+        
+        this.setState({ isResizing: true });
+        
+        // Simple event handlers - no complex bound references
+        const handleMove = (e: MouseEvent | TouchEvent | PointerEvent) => {
+            const clientX = 'touches' in e ? e.touches[0].clientX : e.clientX;
+            
+            if (!this.state.isResizing) {
+                return;
+            }
+            
+            // For mouse events, check if button is still pressed
+            // Skip button checking for pointer events as they may have different button state behavior
+            if (e.type === 'mousemove' && 'buttons' in e && e.buttons !== 1) {
+                handleEnd();
+                return;
+            }
+            
+            e.preventDefault();
+            
+            const viewportWidth = window.innerWidth;
+            const newWidthPx = Math.max(0, viewportWidth - clientX);
+            const newWidthPercent = (newWidthPx / viewportWidth) * 100;
+            
+            const minWidthPercent = 20;
+            const maxWidthPercent = 60;
+            const constrainedWidthPercent = Math.min(Math.max(newWidthPercent, minWidthPercent), maxWidthPercent);
+            
+            this.setState({ sideDocsUserWidthPercent: constrainedWidthPercent });
+            
+            const root = document.documentElement;
+            root.style.setProperty('--sidedoc-user-width', `${constrainedWidthPercent}vw`);
+        };
+        
+        const handleEnd = () => {
+            this.setState({ isResizing: false });
+            
+            // Remove all listeners
+            document.removeEventListener('mousemove', handleMove);
+            document.removeEventListener('mouseup', handleEnd);
+            document.removeEventListener('pointermove', handleMove as any);
+            document.removeEventListener('pointerup', handleEnd);
+            document.removeEventListener('touchmove', handleMove);
+            document.removeEventListener('touchend', handleEnd);
+            window.removeEventListener('mouseup', handleEnd);
+            
+            document.body.classList.remove('resizing-sidedocs');
+            
+            // Save preference
+            const widthPercent = this.state.sideDocsUserWidthPercent;
+            if (widthPercent) {
+                const announcement = lf("Documentation panel resized to {0}% of screen width", Math.round(widthPercent));
+                pxt.debug(announcement);
+                pxt.storage.setLocal("sidedocs-width-percent", widthPercent.toString());
+            }
+        };
+        
+        // Add listeners
+        document.addEventListener('mousemove', handleMove);
+        document.addEventListener('mouseup', handleEnd);
+        document.addEventListener('pointermove', handleMove as any);
+        document.addEventListener('pointerup', handleEnd);
+        document.addEventListener('touchmove', handleMove);
+        document.addEventListener('touchend', handleEnd);
+        window.addEventListener('mouseup', handleEnd); // Catch mouseup outside window
+        
+        document.body.classList.add('resizing-sidedocs');
+        
+        const announcement = lf("Resizing documentation panel");
+        pxt.debug(announcement);
+    }
+
+    private handleResizeKeyDown(e: React.KeyboardEvent) {
+        const step = e.shiftKey ? 5 : 2; // Percentage steps (5% with Shift, 2% normally)
+        let currentWidthPercent = this.state.sideDocsUserWidthPercent;
+        
+        // If no user width set, calculate current width as percentage
+        if (!currentWidthPercent) {
+            const currentWidthPx = this.state.sideDocsWidthPx || (window.innerWidth * 0.3); // Default to 30%
+            currentWidthPercent = (currentWidthPx / window.innerWidth) * 100;
+        }
+        
+        let newWidthPercent = currentWidthPercent;
+        
+        switch (e.key) {
+            case 'ArrowRight':
+                e.preventDefault();
+                newWidthPercent = Math.max(currentWidthPercent - step, 20); // Min 20%
+                break;
+            case 'ArrowLeft': 
+                e.preventDefault();
+                newWidthPercent = Math.min(currentWidthPercent + step, 60); // Max 60%
+                break;
+            case 'Home':
+                e.preventDefault();
+                newWidthPercent = 20; // minimum width
+                break;
+            case 'End':
+                e.preventDefault();
+                newWidthPercent = 60; // maximum width
+                break;
+            case 'Escape':
+                e.preventDefault();
+                if (this.resizeHandleRef.current) {
+                    this.resizeHandleRef.current.blur();
+                }
+                return;
+            default:
+                return;
+        }
+        
+        this.setState({ sideDocsUserWidthPercent: newWidthPercent });
+        const root = document.documentElement;
+        root.style.setProperty('--sidedoc-user-width', `${newWidthPercent}vw`);
+        
+        // Save preference
+        pxt.storage.setLocal("sidedocs-width-percent", newWidthPercent.toString());
+        
+        // Announce to screen readers
+        const announcement = lf("Documentation panel width: {0}% of screen", Math.round(newWidthPercent));
+        pxt.debug(announcement);
+    }
+
     renderCore() {
         const tabs = this.buildTabs();
         // If activeTabId is not set, defer to the incoming props to determine if the current prop url is a built-in.
         const activeTabId = this.state.activeTabId || (this.props.docsUrl && this.props.docsUrl.startsWith(builtInPrefix) ? this.getBuiltInKeyFromUrl(this.props.docsUrl as string) || 'docs-iframe' : 'docs-iframe');
         const activeTab = tabs.find(t => t.id === activeTabId) || tabs[0];
 
-        const { sideDocsCollapsed, docsIframeUrl } = this.state;
+        const { sideDocsCollapsed, docsIframeUrl, isResizing, sideDocsUserWidthPercent } = this.state;
         const lockedEditor = !!pxt.appTarget.appTheme.lockedEditor;
 
         const url = (activeTab.id === 'docs-iframe') ? (sideDocsCollapsed ? this.rootDocsUrl() : (docsIframeUrl || (this.props.docsUrl && !this.props.docsUrl.startsWith(builtInPrefix) ? this.props.docsUrl : this.rootDocsUrl()))) : (activeTab.builtInKey ? `${builtInPrefix}${activeTab.builtInKey}` : '');
@@ -1110,6 +1278,23 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             <sui.Icon icon="external" />
         </a>;
 
+        const resizeHandle = <div
+            ref={this.resizeHandleRef}
+            className={`sidedocs-resize-handle ${isResizing ? 'resizing' : ''}`}
+            role="separator"
+            aria-orientation="vertical"
+            aria-label={lf("Resize documentation panel")}
+            aria-valuenow={sideDocsUserWidthPercent ? Math.round(sideDocsUserWidthPercent) : Math.round((this.state.sideDocsWidthPx / window.innerWidth) * 100)}
+            aria-valuemin={20}
+            aria-valuemax={60}
+            tabIndex={0}
+            title={lf("Drag to resize panel, or use arrow keys. Press Escape to finish.")}
+            onPointerDown={this.handleResizeStart}
+            onMouseDown={this.handleResizeStart}
+            onTouchStart={this.handleResizeStart}
+            onKeyDown={this.handleResizeKeyDown}
+        />;
+
         const headerBar = <div className="sidedoc-header" role="banner">
             <div className="sidedoc-title">{this.props.sideDocsTitle || lf("Docs")}</div>
             <div className="sidedoc-controls">
@@ -1125,7 +1310,7 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             </div>
         </div>;
 
-        const contentParts = [content];
+        const contentParts = [resizeHandle, content];
 
         /* eslint-disable @microsoft/sdl/react-iframe-missing-sandbox */
         return <div>

From d016e9ae7f3003c935d61e213d8e65195b2d8571 Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Mon, 8 Sep 2025 16:30:43 -0700
Subject: [PATCH 09/16] resize tweaks

---
 theme/sidedoc.less       |  9 +++++++++
 webapp/src/container.tsx | 22 ++++++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/theme/sidedoc.less b/theme/sidedoc.less
index 7e63912bad33..cee5a74002de 100644
--- a/theme/sidedoc.less
+++ b/theme/sidedoc.less
@@ -233,6 +233,15 @@ code.hljs {
         outline-offset: 2px;
     }
 
+    /* Suppress hover effects when another drag operation is active */
+    &.drag-disabled {
+        cursor: default;
+        
+        &:hover {
+            background: transparent;
+        }
+    }
+
     /* Hide on mobile to avoid accidental touches */
     @media only screen and (max-width: @largestMobileScreen) {
         display: none;
diff --git a/webapp/src/container.tsx b/webapp/src/container.tsx
index 3af11651d6d5..53cffa781ece 100644
--- a/webapp/src/container.tsx
+++ b/webapp/src/container.tsx
@@ -1199,6 +1199,26 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         pxt.debug(announcement);
     }
 
+    private handleResizeHover = (e: React.MouseEvent) => {
+        // Check if there's already a drag operation in progress
+        // If mouse buttons are pressed (but not specifically on our handle), suppress hover effects
+        if (e.buttons > 0) {
+            // Remove hover styling to indicate the handle is not interactive during other drag operations
+            const handle = this.resizeHandleRef.current;
+            if (handle) {
+                handle.classList.add('drag-disabled');
+            }
+        }
+    };
+
+    private handleResizeHoverEnd = (e: React.MouseEvent) => {
+        // Remove the drag-disabled class when mouse leaves
+        const handle = this.resizeHandleRef.current;
+        if (handle) {
+            handle.classList.remove('drag-disabled');
+        }
+    };
+
     private handleResizeKeyDown(e: React.KeyboardEvent) {
         const step = e.shiftKey ? 5 : 2; // Percentage steps (5% with Shift, 2% normally)
         let currentWidthPercent = this.state.sideDocsUserWidthPercent;
@@ -1293,6 +1313,8 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             onMouseDown={this.handleResizeStart}
             onTouchStart={this.handleResizeStart}
             onKeyDown={this.handleResizeKeyDown}
+            onMouseEnter={this.handleResizeHover}
+            onMouseLeave={this.handleResizeHoverEnd}
         />;
 
         const headerBar = <div className="sidedoc-header" role="banner">

From 62aa78564f7c2f3e1c077b3f1cdd0bf27024ea65 Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Tue, 9 Sep 2025 14:23:33 -0700
Subject: [PATCH 10/16] lint

---
 cli/cli.ts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/cli/cli.ts b/cli/cli.ts
index ec0692829eb0..65133a59aa20 100644
--- a/cli/cli.ts
+++ b/cli/cli.ts
@@ -2819,7 +2819,7 @@ function buildAndWatchAsync(f: () => Promise<string[]>, maxDepth: number): Promi
         .then(dirs => {
             if (globalConfig.noAutoBuild) return
             pxt.debug('watching ' + dirs.join(', ') + '...');
-            
+
             let loop = () => {
                 // Skip polling if we're currently building or debouncing
                 if (isBuilding || debounceTimer) {
@@ -2832,7 +2832,7 @@ function buildAndWatchAsync(f: () => Promise<string[]>, maxDepth: number): Promi
                     .then(num => {
                         if (num > currMtime) {
                             currMtime = num;
-                            
+
                             // Clear any existing debounce timer
                             if (debounceTimer) {
                                 clearTimeout(debounceTimer);
@@ -2843,7 +2843,7 @@ function buildAndWatchAsync(f: () => Promise<string[]>, maxDepth: number): Promi
                             debounceTimer = setTimeout(() => {
                                 debounceTimer = null;
                                 isBuilding = true;
-                                
+
                                 f()
                                     .then(d => {
                                         dirs = d;
@@ -2857,7 +2857,7 @@ function buildAndWatchAsync(f: () => Promise<string[]>, maxDepth: number): Promi
                                     });
                             }, DEBOUNCE_MS);
                         }
-                        
+
                         // Continue polling regardless of whether we detected changes
                         U.nextTick(loop);
                     })
@@ -2867,7 +2867,7 @@ function buildAndWatchAsync(f: () => Promise<string[]>, maxDepth: number): Promi
                         U.nextTick(loop);
                     });
             };
-            
+
             U.nextTick(loop);
         });
 }

From 093d2d77b886e8ee04f559607868b74d506e67cb Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Tue, 9 Sep 2025 15:01:12 -0700
Subject: [PATCH 11/16] moar lint

---
 webapp/src/container.tsx | 58 ++++++++++++++++++++--------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/webapp/src/container.tsx b/webapp/src/container.tsx
index 53cffa781ece..8cea5beee8b9 100644
--- a/webapp/src/container.tsx
+++ b/webapp/src/container.tsx
@@ -966,7 +966,7 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
     componentDidMount() {
         window.addEventListener('resize', this.updateLayoutMeasurements);
         this.updateLayoutMeasurements();
-        
+
         // Load saved width preference
         const savedWidthPercent = pxt.storage.getLocal("sidedocs-width-percent");
         if (savedWidthPercent) {
@@ -994,7 +994,7 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         }
 
         this.updateLayoutMeasurements();
-        
+
         // Apply user-set width if available
         if (this.state.sideDocsUserWidthPercent) {
             const root = document.documentElement;
@@ -1117,53 +1117,53 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
     private handleResizeStart(e: React.MouseEvent | React.TouchEvent | React.PointerEvent) {
         e.preventDefault();
         e.stopPropagation();
-        
+
         if (this.state.isResizing) {
             return;
         }
-        
+
         // Capture pointer events to ensure we get all mouse movements
         const target = e.currentTarget as HTMLElement;
         if ('pointerId' in e.nativeEvent && 'setPointerCapture' in target) {
             target.setPointerCapture((e.nativeEvent as PointerEvent).pointerId);
         }
-        
+
         this.setState({ isResizing: true });
-        
+
         // Simple event handlers - no complex bound references
         const handleMove = (e: MouseEvent | TouchEvent | PointerEvent) => {
             const clientX = 'touches' in e ? e.touches[0].clientX : e.clientX;
-            
+
             if (!this.state.isResizing) {
                 return;
             }
-            
+
             // For mouse events, check if button is still pressed
             // Skip button checking for pointer events as they may have different button state behavior
             if (e.type === 'mousemove' && 'buttons' in e && e.buttons !== 1) {
                 handleEnd();
                 return;
             }
-            
+
             e.preventDefault();
-            
+
             const viewportWidth = window.innerWidth;
             const newWidthPx = Math.max(0, viewportWidth - clientX);
             const newWidthPercent = (newWidthPx / viewportWidth) * 100;
-            
+
             const minWidthPercent = 20;
             const maxWidthPercent = 60;
             const constrainedWidthPercent = Math.min(Math.max(newWidthPercent, minWidthPercent), maxWidthPercent);
-            
+
             this.setState({ sideDocsUserWidthPercent: constrainedWidthPercent });
-            
+
             const root = document.documentElement;
             root.style.setProperty('--sidedoc-user-width', `${constrainedWidthPercent}vw`);
         };
-        
+
         const handleEnd = () => {
             this.setState({ isResizing: false });
-            
+
             // Remove all listeners
             document.removeEventListener('mousemove', handleMove);
             document.removeEventListener('mouseup', handleEnd);
@@ -1172,9 +1172,9 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             document.removeEventListener('touchmove', handleMove);
             document.removeEventListener('touchend', handleEnd);
             window.removeEventListener('mouseup', handleEnd);
-            
+
             document.body.classList.remove('resizing-sidedocs');
-            
+
             // Save preference
             const widthPercent = this.state.sideDocsUserWidthPercent;
             if (widthPercent) {
@@ -1183,7 +1183,7 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
                 pxt.storage.setLocal("sidedocs-width-percent", widthPercent.toString());
             }
         };
-        
+
         // Add listeners
         document.addEventListener('mousemove', handleMove);
         document.addEventListener('mouseup', handleEnd);
@@ -1192,9 +1192,9 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         document.addEventListener('touchmove', handleMove);
         document.addEventListener('touchend', handleEnd);
         window.addEventListener('mouseup', handleEnd); // Catch mouseup outside window
-        
+
         document.body.classList.add('resizing-sidedocs');
-        
+
         const announcement = lf("Resizing documentation panel");
         pxt.debug(announcement);
     }
@@ -1222,21 +1222,21 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
     private handleResizeKeyDown(e: React.KeyboardEvent) {
         const step = e.shiftKey ? 5 : 2; // Percentage steps (5% with Shift, 2% normally)
         let currentWidthPercent = this.state.sideDocsUserWidthPercent;
-        
+
         // If no user width set, calculate current width as percentage
         if (!currentWidthPercent) {
             const currentWidthPx = this.state.sideDocsWidthPx || (window.innerWidth * 0.3); // Default to 30%
             currentWidthPercent = (currentWidthPx / window.innerWidth) * 100;
         }
-        
+
         let newWidthPercent = currentWidthPercent;
-        
+
         switch (e.key) {
             case 'ArrowRight':
                 e.preventDefault();
                 newWidthPercent = Math.max(currentWidthPercent - step, 20); // Min 20%
                 break;
-            case 'ArrowLeft': 
+            case 'ArrowLeft':
                 e.preventDefault();
                 newWidthPercent = Math.min(currentWidthPercent + step, 60); // Max 60%
                 break;
@@ -1257,14 +1257,14 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             default:
                 return;
         }
-        
+
         this.setState({ sideDocsUserWidthPercent: newWidthPercent });
         const root = document.documentElement;
         root.style.setProperty('--sidedoc-user-width', `${newWidthPercent}vw`);
-        
+
         // Save preference
         pxt.storage.setLocal("sidedocs-width-percent", newWidthPercent.toString());
-        
+
         // Announce to screen readers
         const announcement = lf("Documentation panel width: {0}% of screen", Math.round(newWidthPercent));
         pxt.debug(announcement);
@@ -1358,7 +1358,7 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
                              this.collapse();
                          }
                      };
- 
+
                      return tabs.map((t, i) => {
                          const isActive = t.id === activeTabId;
                         return (
@@ -1437,4 +1437,4 @@ export class SandboxFooter extends data.PureComponent<SandboxFooterProps, {}> {
             <span className="item"><a role="button" className="ui thin portrait only" title={compileTooltip} onClick={this.compile}><sui.Icon icon={`icon ${pxt.appTarget.appTheme.downloadIcon || 'download'}`} />{pxt.appTarget.appTheme.useUploadMessage ? lf("Upload") : lf("Download")}</a></span>
         </div>;
     }
-}
\ No newline at end of file
+}

From 4a91580e5a0187773ff5ff6b6e509d37df3a35c3 Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Thu, 18 Sep 2025 08:54:30 -0700
Subject: [PATCH 12/16] fix tab bug

---
 webapp/src/app.tsx         |  25 +++++--
 webapp/src/container.tsx   | 134 ++++++++++++++++++++++---------------
 webapp/src/copilotChat.tsx |  66 ++++++++++++++++++
 3 files changed, 168 insertions(+), 57 deletions(-)
 create mode 100644 webapp/src/copilotChat.tsx

diff --git a/webapp/src/app.tsx b/webapp/src/app.tsx
index 3f564f29828b..1a1018a4d0fa 100644
--- a/webapp/src/app.tsx
+++ b/webapp/src/app.tsx
@@ -47,6 +47,7 @@ import * as headerbar from "./headerbar";
 import * as sidepanel from "./sidepanel";
 import * as qr from "./qr";
 import { ThemePickerModal } from "../../react-common/components/theming/ThemePickerModal";
+import { CopilotChat } from "./copilotChat";
 
 import * as monaco from "./monaco"
 import * as toolboxHelpers from "./toolboxHelpers"
@@ -205,7 +206,9 @@ export class ProjectView
             isMultiplayerGame: false,
             activeTourConfig: undefined,
             mute: pxt.editor.MuteState.Unmuted,
-            feedback: {showing: false, kind: "generic"} // state that tracks if the feedback modal is showing and what kind
+            feedback: {showing: false, kind: "generic"}, // state that tracks if the feedback modal is showing and what kind
+            sideDocsCollapsed: true, // Start with sidedocs hidden
+            sideDocsLoadUrl: '' // Start with no URL loaded
         };
         if (!this.settings.editorFontSize) this.settings.editorFontSize = /mobile/i.test(navigator.userAgent) ? 15 : 19;
         if (!this.settings.fileHistory) this.settings.fileHistory = [];
@@ -1853,6 +1856,7 @@ export class ProjectView
                 projectName: h.name,
                 currFile: file,
                 sideDocsLoadUrl: sideDocsLoadUrl,
+                sideDocsCollapsed: !sideDocsLoadUrl,
                 debugging: false,
                 isMultiplayerGame: false
             });
@@ -2784,7 +2788,7 @@ export class ProjectView
         return Util.promiseTimeout(1000, this.requestScreenshotPromise = new Promise<string>((resolve, reject) => {
             this.pushScreenshotHandler(msg => resolve(pxt.BrowserUtils.imageDataToPNG(msg.data, 3)));
         })) // simulator might be stopped or in bad shape
-            .catch(e => {
+            .catch((e: unknown): undefined => {
                 pxt.tickEvent('screenshot.timeout');
                 return undefined;
             })
@@ -5500,7 +5504,7 @@ export class ProjectView
         const feedbackEnabled = pxt.U.ocvEnabled();
         const showEditorToolbar = inEditor && !hideEditorToolbar && this.editor.hasEditorToolbar();
         const useSerialEditor = pxt.appTarget.serial && !!pxt.appTarget.serial.useEditor;
-        const showSideDoc = sideDocs && this.state.sideDocsLoadUrl && !this.state.sideDocsCollapsed;
+        const showSideDoc = sideDocs && this.state.sideDocsCollapsed === false;
         const showCollapseButton = showEditorToolbar && !inHome && !sandbox && !targetTheme.simCollapseInMenu && (!isHeadless || inDebugMode) && !isTabTutorial;
         const shouldHideEditorFloats = this.state.hideEditorFloats || this.state.collapseEditorTools;
         const logoWide = !!targetTheme.logoWide;
@@ -5625,7 +5629,20 @@ export class ProjectView
                         <projects.Projects parent={this} ref={this.handleHomeRef} />
                     </div>
                 </div> : undefined}
-                {sideDocs ? <container.SideDocs ref="sidedoc" parent={this} sideDocsCollapsed={this.state.sideDocsCollapsed} docsUrl={this.state.sideDocsLoadUrl} /> : undefined}
+                {sideDocs ? <container.SideDocs 
+                    ref="sidedoc" 
+                    parent={this} 
+                    sideDocsCollapsed={this.state.sideDocsCollapsed} 
+                    docsUrl={this.state.sideDocsLoadUrl}
+                    extraTabs={[
+                        {
+                            id: "copilot-chat",
+                            title: lf("Chat"),
+                            icon: "comment",
+                            component: () => <CopilotChat />
+                        }
+                    ]}
+                /> : undefined}
                 {showEditorToolbar && <editortoolbar.EditorToolbar ref="editortools" parent={this} />}
                 {sandbox ? undefined : <scriptsearch.ScriptSearch parent={this} ref={this.handleScriptSearchRef} />}
                 {sandbox ? undefined : <extensions.Extensions parent={this} ref={this.handleExtensionRef} />}
diff --git a/webapp/src/container.tsx b/webapp/src/container.tsx
index 8cea5beee8b9..bf9273bb7f67 100644
--- a/webapp/src/container.tsx
+++ b/webapp/src/container.tsx
@@ -127,7 +127,7 @@ export class DocsMenu extends data.PureComponent<DocsMenuProps, {}> {
             role: "menuitem",
             label: pxt.Util.rlf(this.props.editor),
             title: pxt.Util.rlf(this.props.editor),
-            onClick: () => openDocs(parent,  "/" + editor.toLowerCase())
+            onClick: () => openDocs(parent, "/" + editor.toLowerCase())
         });
 
         return (
@@ -643,7 +643,7 @@ class JavascriptMenuItem extends data.Component<ISettingsProps, {}> {
     }
 
     renderCore() {
-        return <BaseMenuItemProps className="javascript-menuitem" icon="xicon js" text="JavaScript" title={lf("Convert code to JavaScript")} onClick={this.onClick} isActive={this.isActive} parent={this.props.parent} ariaLabel={lf("Convert code to JavaScript")}/>
+        return <BaseMenuItemProps className="javascript-menuitem" icon="xicon js" text="JavaScript" title={lf("Convert code to JavaScript")} onClick={this.onClick} isActive={this.isActive} parent={this.props.parent} ariaLabel={lf("Convert code to JavaScript")} />
     }
 }
 
@@ -681,7 +681,7 @@ class BlocksMenuItem extends data.Component<ISettingsProps, {}> {
     }
 
     renderCore() {
-        return <BaseMenuItemProps className="blocks-menuitem" icon="xicon blocks" text={lf("Blocks")} title={lf("Convert code to Blocks")} onClick={this.onClick} isActive={this.isActive} parent={this.props.parent} ariaLabel={lf("Convert code to Blocks")}/>
+        return <BaseMenuItemProps className="blocks-menuitem" icon="xicon blocks" text={lf("Blocks")} title={lf("Convert code to Blocks")} onClick={this.onClick} isActive={this.isActive} parent={this.props.parent} ariaLabel={lf("Convert code to Blocks")} />
     }
 }
 
@@ -761,18 +761,18 @@ export class EditorSelector extends data.Component<IEditorSelectorProps, {}> {
         let secondTextLanguage: JSX.Element = undefined;
 
         if (showDropdown) {
-            if (pythonIsActive) textLanguage = <PythonMenuItem parent={parent}/>
-            else textLanguage = <JavascriptMenuItem parent={parent}/>
+            if (pythonIsActive) textLanguage = <PythonMenuItem parent={parent} />
+            else textLanguage = <JavascriptMenuItem parent={parent} />
         }
         else if (showPython && showJavaScript) {
-            textLanguage = <JavascriptMenuItem parent={parent}/>;
-            secondTextLanguage  = <PythonMenuItem parent={parent}/>;
+            textLanguage = <JavascriptMenuItem parent={parent} />;
+            secondTextLanguage = <PythonMenuItem parent={parent} />;
         }
         else if (showPython) {
-            textLanguage = <PythonMenuItem parent={parent}/>;
+            textLanguage = <PythonMenuItem parent={parent} />;
         }
         else if (showJavaScript) {
-            textLanguage = <JavascriptMenuItem parent={parent}/>
+            textLanguage = <JavascriptMenuItem parent={parent} />
         }
 
         return (
@@ -927,7 +927,7 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
     }
 
     private setUrl(url: string) {
-        this.props.parent.setState({ sideDocsLoadUrl: url, sideDocsCollapsed: false });
+        this.props.parent.setState({ sideDocsLoadUrl: url });
         // store last non-built-in docs url in state.docsIframeUrl so iframe tab has its own url cache
         if (!url.startsWith(builtInPrefix)) {
             this.setState({ docsIframeUrl: url, activeTabId: 'docs-iframe' });
@@ -1008,12 +1008,20 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             newState.sideDocsCollapsed = nextProps.sideDocsCollapsed;
         }
         if (nextProps.docsUrl != undefined) {
-            // If incoming docsUrl indicates a built-in, set active tab accordingly; otherwise track it as the iframe URL
-            if (nextProps.docsUrl && nextProps.docsUrl.startsWith(builtInPrefix)) {
+            // Handle component URLs (component:tabId)
+            if (nextProps.docsUrl && nextProps.docsUrl.startsWith('component:')) {
+                const componentTabId = nextProps.docsUrl.slice('component:'.length);
+                newState.activeTabId = componentTabId;
+                // Don't set docsIframeUrl for component tabs
+            }
+            // If incoming docsUrl indicates a built-in, set active tab accordingly
+            else if (nextProps.docsUrl && nextProps.docsUrl.startsWith(builtInPrefix)) {
                 const key = this.getBuiltInKeyFromUrl(nextProps.docsUrl);
                 if (key) newState.activeTabId = key;
                 else newState.activeTabId = 'docs-iframe';
-            } else {
+            }
+            // Otherwise track it as the iframe URL
+            else {
                 newState.docsIframeUrl = nextProps.docsUrl;
                 newState.activeTabId = 'docs-iframe';
             }
@@ -1060,8 +1068,10 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         }
 
         if (this.props.extraTabs) {
-            for (const et of this.props.extraTabs) {
-                const tid = et.id || `extra-${Math.random().toString(36).slice(2, 8)}`;
+            for (const i in this.props.extraTabs) {
+                const et = this.props.extraTabs[i];
+                if (!et) continue;
+                const tid = et.id || `extra-tab-${i}`;
                 tabs.push({ id: tid, title: et.title, icon: et.icon, component: et.component });
             }
         }
@@ -1073,6 +1083,10 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         const tabs = this.buildTabs();
         const tab = tabs.find(t => t.id === tabId);
         if (!tab) return;
+
+        // Always expand the panel when a tab is selected
+        this.props.parent.setState({ sideDocsCollapsed: false });
+
         if (tab.builtInKey) {
             const url = builtInPrefix + tab.builtInKey;
             this.setUrl(url);
@@ -1083,9 +1097,11 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             const candidateFromProps = (this.props.docsUrl && !this.props.docsUrl.startsWith(builtInPrefix)) ? this.props.docsUrl : undefined;
             const url = candidateFromState || candidateFromProps || this.rootDocsUrl();
             this.setUrl(url);
+            this.setState({ activeTabId: tabId });
         } else if (tab.component) {
             this.setState({ activeTabId: tabId });
-            this.props.parent.setState({ sideDocsLoadUrl: '', sideDocsCollapsed: false });
+            // Set a special URL to indicate component tab is active
+            this.props.parent.setState({ sideDocsLoadUrl: 'component:' + tabId });
         }
     }
 
@@ -1279,7 +1295,12 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         const { sideDocsCollapsed, docsIframeUrl, isResizing, sideDocsUserWidthPercent } = this.state;
         const lockedEditor = !!pxt.appTarget.appTheme.lockedEditor;
 
-        const url = (activeTab.id === 'docs-iframe') ? (sideDocsCollapsed ? this.rootDocsUrl() : (docsIframeUrl || (this.props.docsUrl && !this.props.docsUrl.startsWith(builtInPrefix) ? this.props.docsUrl : this.rootDocsUrl()))) : (activeTab.builtInKey ? `${builtInPrefix}${activeTab.builtInKey}` : '');
+        // Calculate URL - only for iframe and built-in tabs, not for component tabs
+        const url = activeTab.component ? '' : (
+            (activeTab.id === 'docs-iframe') ?
+                (sideDocsCollapsed ? this.rootDocsUrl() : (docsIframeUrl || (this.props.docsUrl && !this.props.docsUrl.startsWith(builtInPrefix) ? this.props.docsUrl : this.rootDocsUrl()))) :
+                (activeTab.builtInKey ? `${builtInPrefix}${activeTab.builtInKey}` : '')
+        );
 
         const builtInDetail = url && url.startsWith(builtInPrefix) ? builtIns[url.slice(builtInPrefix.length) as pxt.editor.BuiltInHelp] : undefined;
         const openInNewTabLinkProps: React.ComponentProps<'a'> = builtInDetail ? {
@@ -1337,30 +1358,30 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         /* eslint-disable @microsoft/sdl/react-iframe-missing-sandbox */
         return <div>
             {/* tab strip */}
-             <div id="sidedocstabs" role="tablist" className="sidedoc-tablist" aria-orientation="vertical">
-                 {(() => {
-                     const onTabKeyDown = (ev: React.KeyboardEvent<HTMLElement>, idx: number) => {
-                         const key = ev.key;
-                         if (key === 'ArrowUp' || key === 'ArrowDown' || key === 'Home' || key === 'End') {
-                             ev.preventDefault();
-                             let newIdx = idx;
-                             if (key === 'ArrowUp') newIdx = (idx - 1 + tabs.length) % tabs.length;
-                             else if (key === 'ArrowDown') newIdx = (idx + 1) % tabs.length;
-                             else if (key === 'Home') newIdx = 0;
-                             else if (key === 'End') newIdx = tabs.length - 1;
-                             const tabBtn = document.getElementById('sidedocstabs')?.querySelectorAll('button')[newIdx] as HTMLButtonElement;
-                             if (tabBtn) {
-                                 tabBtn.focus();
-                                 // invoke selectTab directly to ensure state is in sync
-                                 this.selectTab(tabs[newIdx].id);
-                             }
-                         } else if (key === 'Escape') {
-                             this.collapse();
-                         }
-                     };
-
-                     return tabs.map((t, i) => {
-                         const isActive = t.id === activeTabId;
+            <div id="sidedocstabs" role="tablist" className="sidedoc-tablist" aria-orientation="vertical">
+                {(() => {
+                    const onTabKeyDown = (ev: React.KeyboardEvent<HTMLElement>, idx: number) => {
+                        const key = ev.key;
+                        if (key === 'ArrowUp' || key === 'ArrowDown' || key === 'Home' || key === 'End') {
+                            ev.preventDefault();
+                            let newIdx = idx;
+                            if (key === 'ArrowUp') newIdx = (idx - 1 + tabs.length) % tabs.length;
+                            else if (key === 'ArrowDown') newIdx = (idx + 1) % tabs.length;
+                            else if (key === 'Home') newIdx = 0;
+                            else if (key === 'End') newIdx = tabs.length - 1;
+                            const tabBtn = document.getElementById('sidedocstabs')?.querySelectorAll('button')[newIdx] as HTMLButtonElement;
+                            if (tabBtn) {
+                                tabBtn.focus();
+                                // invoke selectTab directly to ensure state is in sync
+                                this.selectTab(tabs[newIdx].id);
+                            }
+                        } else if (key === 'Escape') {
+                            this.collapse();
+                        }
+                    };
+
+                    return tabs.map((t, i) => {
+                        const isActive = t.id === activeTabId;
                         return (
                             <div key={t.id} title={t.title || ''} className={`sidedoc-tab ${isActive ? 'active' : ''}`}>
                                 <sui.Button
@@ -1377,18 +1398,20 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
                                 />
                             </div>
                         );
-                     });
-                 })()}
-             </div>
-             <div id="sidedocs" onKeyDown={this.handleKeyDown}>
-                 {!sideDocsCollapsed ? contentParts : null}
-             </div>
-         </div>
-         /* eslint-enable @microsoft/sdl/react-iframe-missing-sandbox */
-     }
+                    });
+                })()}
+            </div>
+            <div id="sidedocs" onKeyDown={this.handleKeyDown}>
+                {!sideDocsCollapsed ? contentParts : null}
+            </div>
+        </div>
+        /* eslint-enable @microsoft/sdl/react-iframe-missing-sandbox */
+    }
 
     renderTabContent(tab: SideDocsTab, url: string, builtInDetail: BuiltInHelpDetails | undefined, lockedEditor: boolean) {
         if (!tab) return null;
+
+        // Handle component tabs (like Chat)
         if (tab.component) {
             const TabComponent = tab.component;
             try {
@@ -1398,9 +1421,14 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             }
         }
 
-        // If no tab.component provided, fall back to iframe/built-in handling
-        const BuiltInComponent = builtInDetail?.component;
-        return BuiltInComponent ? <BuiltInComponent /> : (
+        // Handle built-in help tabs (like Keyboard Help)
+        if (builtInDetail?.component) {
+            const BuiltInComponent = builtInDetail.component;
+            return <BuiltInComponent />;
+        }
+
+        // Show iframe tab (Docs)
+        return (
             <iframe id="sidedocsframe" src={url} title={lf("Documentation")} aria-atomic="true" aria-live="assertive"
                 sandbox={`allow-scripts allow-same-origin allow-forms ${lockedEditor ? "" : "allow-popups"}`} />
         );
diff --git a/webapp/src/copilotChat.tsx b/webapp/src/copilotChat.tsx
new file mode 100644
index 000000000000..957b3ad4539c
--- /dev/null
+++ b/webapp/src/copilotChat.tsx
@@ -0,0 +1,66 @@
+/** @format */
+/// <reference path="../../built/pxtlib.d.ts" />
+
+import * as React from "react";
+import { Chat } from "../../react-common/components/controls/Chat/Chat";
+import { Message } from "../../react-common/components/controls/Chat/chat.types";
+
+export interface CopilotChatProps {
+    // Add any additional props specific to the copilot chat integration
+}
+
+export const CopilotChat: React.FC<CopilotChatProps> = (props) => {
+    const [messages, setMessages] = React.useState<Message[]>([
+        {
+            id: "welcome",
+            parts: [{ kind: "text", text: "Hello! I'm your coding assistant. How can I help you today?" }],
+            author: "assistant",
+            timestamp: new Date().toISOString(),
+        }
+    ]);
+
+    const handleSend = React.useCallback((messageOrText: Message | string) => {
+        let message: Message;
+        if (typeof messageOrText === "string") {
+            message = {
+                id: `user-${Date.now()}`,
+                parts: [{ kind: "text", text: messageOrText }],
+                author: "user",
+                timestamp: new Date().toISOString(),
+            };
+        } else {
+            message = messageOrText;
+        }
+
+        setMessages(prev => [...prev, message]);
+
+        // TODO: Integrate with actual copilot service
+        // For now, just echo back a simple response
+        setTimeout(() => {
+            const response: Message = {
+                id: `assistant-${Date.now()}`,
+                parts: [{ kind: "text", text: `I received your message: "${message.parts.find(p => p.kind === "text")?.text || ""}"` }],
+                author: "assistant",
+                timestamp: new Date().toISOString(),
+            };
+            setMessages(prev => [...prev, response]);
+        }, 1000);
+    }, []);
+
+    const handleAppend = React.useCallback((message: Message) => {
+        setMessages(prev => [...prev, message]);
+    }, []);
+
+    return (
+        <div className="copilot-chat-container" style={{ height: "100%", display: "flex", flexDirection: "column" }}>
+            <Chat
+                messages={messages}
+                onSend={handleSend}
+                onAppend={handleAppend}
+                style={{ flex: 1 }}
+            />
+        </div>
+    );
+};
+
+export default CopilotChat;

From 3d0492087b3d6bc06cf982a52093d09ca6301dbc Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Tue, 23 Sep 2025 13:54:19 -0700
Subject: [PATCH 13/16] chat control tidy

---
 .../components/controls/Chat/ChatComposer.tsx |   4 +-
 .../components/controls/Chat/chat.stories.tsx |  10 +-
 react-common/styles/controls/Chat.less        | 138 ++++++++++++------
 webapp/src/copilotChat.tsx                    |   5 -
 4 files changed, 105 insertions(+), 52 deletions(-)

diff --git a/react-common/components/controls/Chat/ChatComposer.tsx b/react-common/components/controls/Chat/ChatComposer.tsx
index 1f1b3b1a8ac6..83d7fdcb173d 100644
--- a/react-common/components/controls/Chat/ChatComposer.tsx
+++ b/react-common/components/controls/Chat/ChatComposer.tsx
@@ -4,6 +4,9 @@ import * as React from "react";
 import { classList, ContainerProps } from "../../util";
 import { Button } from "../Button";
 
+// Localization function - placeholder if not available
+const lf = (s: string) => s;
+
 export interface ChatComposerProps extends ContainerProps {
     onSend: (value: string) => void;
     placeholder?: string;
@@ -91,7 +94,6 @@ export const ChatComposer = (props: ChatComposerProps) => {
                 aria-label={placeholder || lf("Message input")}
                 disabled={disabled}
                 rows={1}
-                style={{ minHeight: "2.5rem", maxHeight: "10rem", resize: "none", overflow: "hidden" }}
                 {...ariaProps}
             />
             <Button
diff --git a/react-common/components/controls/Chat/chat.stories.tsx b/react-common/components/controls/Chat/chat.stories.tsx
index ec4b0db6d194..7f4d8286fa2b 100644
--- a/react-common/components/controls/Chat/chat.stories.tsx
+++ b/react-common/components/controls/Chat/chat.stories.tsx
@@ -32,7 +32,7 @@ const sampleMessages: Message[] = [
 export const Default = () => {
     const [messages, setMessages] = React.useState<Message[]>(sampleMessages);
     return (
-        <div style={{ height: 420, width: 420 }}>
+        <div className="common-chat-story-container">
             <Chat
                 messages={messages}
                 onSend={(msgOrText: any) => {
@@ -58,9 +58,9 @@ export const WithCustomCard = () => {
             render: (part: any, ctx) => {
                 const count = ctx?.uiState?.count || 0;
                 return (
-                    <div style={{ border: "1px solid var(--pxt-neutral-stencil1)", padding: "0.5rem", borderRadius: "0.25rem" }}>
+                    <div className="common-chat-custom-card">
                         <div>{part.title || "Demo Card"}</div>
-                        <div style={{ marginTop: "0.5rem" }}>
+                        <div className="common-chat-custom-card-content">
                             <button className="common-button" onClick={() => ctx.updateUiState?.("count", count + 1)}>
                                 Click +{count}
                             </button>
@@ -76,7 +76,7 @@ export const WithCustomCard = () => {
     ]);
 
     return (
-        <div style={{ height: 420, width: 420 }}>
+        <div className="common-chat-story-container">
             <Chat
                 messages={messages}
                 registry={registry}
@@ -99,7 +99,7 @@ export const LongTranscript = () => {
     const [messages, setMessages] = React.useState<Message[]>(many);
 
     return (
-        <div style={{ height: 420, width: 420 }}>
+        <div className="common-chat-story-container">
             <Chat
                 messages={messages}
                 onSend={(mOrText: any) => {
diff --git a/react-common/styles/controls/Chat.less b/react-common/styles/controls/Chat.less
index 35127df8e9e9..03c46c7ce702 100644
--- a/react-common/styles/controls/Chat.less
+++ b/react-common/styles/controls/Chat.less
@@ -1,5 +1,29 @@
-/* Chat component styles: lightweight, theme-aware using CSS variables */
-
+/* ===============================================
+   Chat Component Styles
+   Lightweight, theme-aware using CSS variables
+   
+   Structure:
+   - .common-chat (main container)
+     - .common-chat-message-list (scrollable message area)
+       - .common-chat-message (individual message)
+         - .common-chat-message-meta (author/timestamp)
+         - .common-chat-message-body (message content)
+           - .common-chat-message-part (individual part)
+             - .common-chat-part-text (text content)
+             - .common-chat-part-image (images)
+             - .common-chat-part-fallback (unknown types)
+     - .common-chat-composer (input area)
+       - .common-chat-composer-textarea (auto-resize input)
+       - .common-chat-send-button (send button)
+   
+   Additional components:
+   - .common-chat-scroll-bottom (scroll helper)
+   - .common-chat-error-* (error states)
+   - .common-chat-story-* (storybook specific)
+   - .common-chat-custom-* (demo/example styles)
+   =============================================== */
+
+/* === Base Container === */
 .common-chat {
     display: flex;
     flex-direction: column;
@@ -13,6 +37,7 @@
     position: relative;
 }
 
+/* === Message List === */
 .common-chat-message-list {
     flex: 1 1 auto;
     overflow-y: auto;
@@ -25,6 +50,7 @@
     -webkit-overflow-scrolling: touch;
 }
 
+/* === Message Structure === */
 .common-chat-message {
     display: flex;
     flex-direction: column;
@@ -53,6 +79,7 @@
     align-items: flex-start;
 }
 
+/* === Message Metadata === */
 .common-chat-message-meta {
     display: flex;
     flex-direction: row;
@@ -68,12 +95,14 @@
     gap: 0.25rem;
 }
 
+/* === Message Parts === */
 .common-chat-message-part {
     max-width: ~"min(72%, 28rem)";
     word-wrap: break-word;
     overflow-wrap: break-word;
 }
 
+/* Text parts */
 .common-chat-part-text {
     background: var(--pxt-neutral-background1);
     color: var(--pxt-neutral-foreground1);
@@ -90,6 +119,7 @@
     -ms-user-select: text;
 }
 
+/* Image parts */
 .common-chat-part-image {
     max-width: 18rem;
     border-radius: 0.35rem;
@@ -113,6 +143,22 @@
     font-size: 0.875rem;
 }
 
+/* Fallback parts */
+.common-chat-part-fallback {
+    background: var(--pxt-neutral-background1);
+    color: var(--pxt-neutral-foreground1);
+    padding: 0.5rem;
+    border-radius: 0.3rem;
+    border: 1px dashed var(--pxt-neutral-stencil1);
+    font-family: monospace;
+    font-size: 0.75rem;
+    white-space: pre-wrap;
+    max-width: 20rem;
+    max-height: 10rem;
+    overflow: auto;
+}
+
+/* === Composer Section === */
 .common-chat-composer {
     display: flex;
     gap: 0.5rem;
@@ -127,6 +173,7 @@
     min-height: 2.5rem;
     max-height: 10rem;
     resize: none;
+    overflow: hidden;
     padding: 0.75rem;
     border-radius: 0.5rem;
     border: 1px solid var(--pxt-neutral-stencil1);
@@ -160,20 +207,8 @@
     }
 }
 
-.common-chat-part-fallback {
-    background: var(--pxt-neutral-background1);
-    color: var(--pxt-neutral-foreground1);
-    padding: 0.5rem;
-    border-radius: 0.3rem;
-    border: 1px dashed var(--pxt-neutral-stencil1);
-    font-family: monospace;
-    font-size: 0.75rem;
-    white-space: pre-wrap;
-    max-width: 20rem;
-    max-height: 10rem;
-    overflow: auto;
-}
-
+/* === UI Elements === */
+/* Demo card component */
 .common-chat-demo-card {
     display: flex;
     flex-direction: column;
@@ -185,7 +220,31 @@
     min-width: 12rem;
 }
 
-/* Error boundary styles */
+/* Scroll to bottom helper */
+.common-chat-scroll-bottom {
+    position: absolute;
+    right: 1rem;
+    bottom: 4.25rem;
+    background: var(--pxt-primary-background);
+    color: var(--pxt-primary-foreground);
+    border: none;
+    border-radius: 50%;
+    width: 2.5rem;
+    height: 2.5rem;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+    transition: all 0.2s ease;
+
+    &:hover {
+        transform: translateY(-1px);
+        box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+    }
+}
+
+/* === Error States === */
 .common-chat-error {
     display: flex;
     align-items: center;
@@ -214,36 +273,33 @@
     font-weight: 500;
 }
 
-/* Loading state */
+/* === Loading States === */
 .common-chat.loading {
     opacity: 0.7;
     pointer-events: none;
 }
 
-/* small scroll to bottom helper */
-.common-chat-scroll-bottom {
-    position: absolute;
-    right: 1rem;
-    bottom: 4.25rem;
-    background: var(--pxt-primary-background);
-    color: var(--pxt-primary-foreground);
-    border: none;
-    border-radius: 50%;
-    width: 2.5rem;
-    height: 2.5rem;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    cursor: pointer;
-    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
-    transition: all 0.2s ease;
+/* === Story-specific styles and demo components === */
+.common-chat-story-container {
+    height: 420px;
+    width: 420px;
+}
 
-    &:hover {
-        transform: translateY(-1px);
-        box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
-    }
+.common-chat-custom-card {
+    border: 1px solid var(--pxt-neutral-stencil1);
+    padding: 0.5rem;
+    border-radius: 0.25rem;
+    background: var(--pxt-neutral-background1);
+}
+
+.common-chat-custom-card-content {
+    margin-top: 0.5rem;
 }
 
+/* ===============================================
+   Accessibility & Responsive Media Queries
+   =============================================== */
+
 /* High contrast mode support */
 @media (prefers-contrast: high) {
     .common-chat-part-text {
@@ -255,7 +311,7 @@
     }
 }
 
-/* Respect reduced-motion */
+/* Respect reduced-motion preferences */
 @media (prefers-reduced-motion: reduce) {
     .common-chat-message {
         animation: none !important;
@@ -280,4 +336,4 @@
     .common-chat-part-text {
         box-shadow: 0 1px 0 rgba(255, 255, 255, 0.05);
     }
-}
\ No newline at end of file
+}
diff --git a/webapp/src/copilotChat.tsx b/webapp/src/copilotChat.tsx
index 957b3ad4539c..bce208bee316 100644
--- a/webapp/src/copilotChat.tsx
+++ b/webapp/src/copilotChat.tsx
@@ -47,16 +47,11 @@ export const CopilotChat: React.FC<CopilotChatProps> = (props) => {
         }, 1000);
     }, []);
 
-    const handleAppend = React.useCallback((message: Message) => {
-        setMessages(prev => [...prev, message]);
-    }, []);
-
     return (
         <div className="copilot-chat-container" style={{ height: "100%", display: "flex", flexDirection: "column" }}>
             <Chat
                 messages={messages}
                 onSend={handleSend}
-                onAppend={handleAppend}
                 style={{ flex: 1 }}
             />
         </div>

From 5699cabbf3e6262b1ba109ec207f80e62eb0e69d Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Tue, 23 Sep 2025 14:16:15 -0700
Subject: [PATCH 14/16] css fix

---
 react-common/styles/controls/Chat.less | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/react-common/styles/controls/Chat.less b/react-common/styles/controls/Chat.less
index 03c46c7ce702..7b464ce23780 100644
--- a/react-common/styles/controls/Chat.less
+++ b/react-common/styles/controls/Chat.less
@@ -48,6 +48,9 @@
     scroll-behavior: smooth;
     /* Ensure proper scrolling on mobile */
     -webkit-overflow-scrolling: touch;
+    /* Ensure proper height constraints for scrolling */
+    min-height: 0;
+    height: 0;
 }
 
 /* === Message Structure === */
@@ -57,6 +60,8 @@
     max-width: 100%;
     opacity: 0;
     animation: messageSlideIn 0.3s ease-out forwards;
+    /* Prevent flex shrinking that causes message squeezing */
+    flex-shrink: 0;
 }
 
 @keyframes messageSlideIn {

From f1af6fb8b6e296c8004f8568371c1a82dcde792a Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Tue, 23 Sep 2025 14:22:32 -0700
Subject: [PATCH 15/16] undo debounce

---
 cli/cli.ts | 62 ++++++++++++------------------------------------------
 1 file changed, 13 insertions(+), 49 deletions(-)

diff --git a/cli/cli.ts b/cli/cli.ts
index 65133a59aa20..76bca81d82a7 100644
--- a/cli/cli.ts
+++ b/cli/cli.ts
@@ -2810,66 +2810,30 @@ function pxtVersion(): string {
 }
 
 function buildAndWatchAsync(f: () => Promise<string[]>, maxDepth: number): Promise<void> {
-    let currMtime = Date.now();
-    const DEBOUNCE_MS = 3000;
-    let debounceTimer: NodeJS.Timeout | null = null;
-    let isBuilding = false;
-
+    let currMtime = Date.now()
     return f()
         .then(dirs => {
             if (globalConfig.noAutoBuild) return
             pxt.debug('watching ' + dirs.join(', ') + '...');
-
             let loop = () => {
-                // Skip polling if we're currently building or debouncing
-                if (isBuilding || debounceTimer) {
-                    U.nextTick(loop);
-                    return;
-                }
-
                 U.delay(1000)
                     .then(() => maxMTimeAsync(dirs, maxDepth))
                     .then(num => {
                         if (num > currMtime) {
-                            currMtime = num;
-
-                            // Clear any existing debounce timer
-                            if (debounceTimer) {
-                                clearTimeout(debounceTimer);
-                                debounceTimer = null;
-                            }
-
-                            // Set up debounced build
-                            debounceTimer = setTimeout(() => {
-                                debounceTimer = null;
-                                isBuilding = true;
-
-                                f()
-                                    .then(d => {
-                                        dirs = d;
-                                        isBuilding = false;
-                                        U.nextTick(loop);
-                                    })
-                                    .catch((e) => {
-                                        buildFailed("debounced build failed: " + (e && e.message ? e.message : ""), e);
-                                        isBuilding = false;
-                                        U.nextTick(loop);
-                                    });
-                            }, DEBOUNCE_MS);
+                            currMtime = num
+                            f()
+                                .then(d => {
+                                    dirs = d
+                                    U.nextTick(loop)
+                                })
+                        } else {
+                            U.nextTick(loop)
                         }
-
-                        // Continue polling regardless of whether we detected changes
-                        U.nextTick(loop);
                     })
-                    .catch((e) => {
-                        // Handle maxMTimeAsync errors gracefully
-                        pxt.debug("Error checking file times: " + (e && e.message ? e.message : ""));
-                        U.nextTick(loop);
-                    });
-            };
+            }
+            U.nextTick(loop)
+        })
 
-            U.nextTick(loop);
-        });
 }
 
 function buildFailed(msg: string, e: any) {
@@ -8091,4 +8055,4 @@ if (require.main === module) {
         }
     }
     mainCli(targetdir);
-}
+}
\ No newline at end of file

From ae251419588a3799094bcdc939b1da050b7f9e7a Mon Sep 17 00:00:00 2001
From: Eric Anderson <eanders@microsoft.com>
Date: Tue, 23 Sep 2025 14:40:00 -0700
Subject: [PATCH 16/16] lint

---
 webapp/src/app.tsx       | 8 ++++----
 webapp/src/container.tsx | 1 +
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/webapp/src/app.tsx b/webapp/src/app.tsx
index 1a1018a4d0fa..45a0a8b30675 100644
--- a/webapp/src/app.tsx
+++ b/webapp/src/app.tsx
@@ -5629,10 +5629,10 @@ export class ProjectView
                         <projects.Projects parent={this} ref={this.handleHomeRef} />
                     </div>
                 </div> : undefined}
-                {sideDocs ? <container.SideDocs 
-                    ref="sidedoc" 
-                    parent={this} 
-                    sideDocsCollapsed={this.state.sideDocsCollapsed} 
+                {sideDocs ? <container.SideDocs
+                    ref="sidedoc"
+                    parent={this}
+                    sideDocsCollapsed={this.state.sideDocsCollapsed}
                     docsUrl={this.state.sideDocsLoadUrl}
                     extraTabs={[
                         {
diff --git a/webapp/src/container.tsx b/webapp/src/container.tsx
index bf9273bb7f67..4be9badf1e5e 100644
--- a/webapp/src/container.tsx
+++ b/webapp/src/container.tsx
@@ -1068,6 +1068,7 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
         }
 
         if (this.props.extraTabs) {
+            // eslint-disable-next-line @typescript-eslint/no-for-in-array
             for (const i in this.props.extraTabs) {
                 const et = this.props.extraTabs[i];
                 if (!et) continue;