@plmbr/notebook-intelligence 5.0.0

package/lib/tour/tour-config.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Admin tour-copy overrides — frontend half.
+ *
+ * The backend reads a YAML/JSON file (path from `NBI_TOUR_CONFIG_PATH`)
+ * and ships the validated overrides via the capabilities response. This
+ * module overlays them on the built-in `ALL_TOUR_STEPS` so the same
+ * tour code runs against either the default copy or an admin-supplied
+ * customization, without rebuilding the extension.
+ *
+ * Defense in depth: the backend already validated shape and length;
+ * the frontend re-applies the same caps here so a backend bug or
+ * future server-side regression can't crash the picker layout.
+ */
+import { ITourStep } from './tour-steps';
+export interface ITourStepOverride {
+    title?: string;
+    description?: string;
+    enabled?: boolean;
+    description_singular?: string;
+    description_plural?: string;
+}
+export interface ITourUiOverride {
+    skip?: string;
+    next?: string;
+    back?: string;
+    done?: string;
+}
+export interface ITourCommandOverride {
+    label?: string;
+}
+export interface ITourOverrides {
+    steps?: Record<string, ITourStepOverride>;
+    ui?: ITourUiOverride;
+    command?: ITourCommandOverride;
+}
+/**
+ * Apply admin-supplied overrides to the canonical step list. Returns a
+ * new array; the input is not mutated.
+ *
+ * Override semantics:
+ *  - `enabled: false` drops the step entirely (filtered out here, in
+ *    addition to whatever `requires()` says).
+ *  - `title` / `description` replace the corresponding fields when set.
+ *  - For `launcher-tiles`, the dynamic thunk continues to run; the
+ *    templates feed into it through the per-step override dict so the
+ *    thunk can use them at resolve time.
+ */
+export declare function applyTourOverrides(steps: readonly ITourStep[], overrides: ITourOverrides | undefined): ITourStep[];
+/**
+ * Pull the per-step override for the launcher-tiles step's templates
+ * (if any). Used by the launcher-tiles description thunk.
+ */
+export declare function launcherTileTemplates(overrides: ITourOverrides | undefined): {
+    singular?: string;
+    plural?: string;
+};
+/**
+ * Resolve a UI button label: admin override if set, otherwise the
+ * default supplied by the caller.
+ */
+export declare function uiLabel(overrides: ITourOverrides | undefined, key: keyof ITourUiOverride, fallback: string): string;
+/**
+ * Resolve the command-palette label for the tour command: admin
+ * override if set, otherwise the default supplied by the caller.
+ */
+export declare function commandLabel(overrides: ITourOverrides | undefined, fallback: string): string;

package/lib/tour/tour-config.js

@@ -0,0 +1,99 @@
+// Copyright (c) Mehmet Bektas <mbektasgh@outlook.com>
+// Per-field length caps. Mirror notebook_intelligence/tour_config.py.
+const MAX_TITLE_CHARS = 80;
+const MAX_DESCRIPTION_CHARS = 400;
+const MAX_BUTTON_LABEL_CHARS = 24;
+const MAX_COMMAND_LABEL_CHARS = 40;
+function clamp(value, limit) {
+    return value.length <= limit ? value : value.slice(0, limit);
+}
+/**
+ * Apply admin-supplied overrides to the canonical step list. Returns a
+ * new array; the input is not mutated.
+ *
+ * Override semantics:
+ *  - `enabled: false` drops the step entirely (filtered out here, in
+ *    addition to whatever `requires()` says).
+ *  - `title` / `description` replace the corresponding fields when set.
+ *  - For `launcher-tiles`, the dynamic thunk continues to run; the
+ *    templates feed into it through the per-step override dict so the
+ *    thunk can use them at resolve time.
+ */
+export function applyTourOverrides(steps, overrides) {
+    if (!overrides || !overrides.steps) {
+        return steps.map(step => ({ ...step }));
+    }
+    const stepOverrides = overrides.steps;
+    const result = [];
+    for (const step of steps) {
+        const override = stepOverrides[step.id];
+        if (!override) {
+            result.push({ ...step });
+            continue;
+        }
+        if (override.enabled === false) {
+            continue;
+        }
+        const next = { ...step };
+        // Reject empty strings: an empty title would leave the dialog's
+        // aria-labelledby target with no accessible name, and an empty
+        // description would leave aria-describedby pointing at nothing.
+        if (typeof override.title === 'string' && override.title.length > 0) {
+            next.title = clamp(override.title, MAX_TITLE_CHARS);
+        }
+        if (typeof override.description === 'string' &&
+            override.description.length > 0 &&
+            // The launcher-tiles thunk is overridden via templates, not the
+            // plain `description` field; the backend validator rejects it
+            // outright, but ignore it here too in case an older payload slips
+            // through.
+            step.id !== 'launcher-tiles') {
+            next.description = clamp(override.description, MAX_DESCRIPTION_CHARS);
+        }
+        result.push(next);
+    }
+    return result;
+}
+/**
+ * Pull the per-step override for the launcher-tiles step's templates
+ * (if any). Used by the launcher-tiles description thunk.
+ */
+export function launcherTileTemplates(overrides) {
+    var _a;
+    const step = (_a = overrides === null || overrides === void 0 ? void 0 : overrides.steps) === null || _a === void 0 ? void 0 : _a['launcher-tiles'];
+    if (!step) {
+        return {};
+    }
+    const result = {};
+    if (typeof step.description_singular === 'string') {
+        result.singular = clamp(step.description_singular, MAX_DESCRIPTION_CHARS);
+    }
+    if (typeof step.description_plural === 'string') {
+        result.plural = clamp(step.description_plural, MAX_DESCRIPTION_CHARS);
+    }
+    return result;
+}
+/**
+ * Resolve a UI button label: admin override if set, otherwise the
+ * default supplied by the caller.
+ */
+export function uiLabel(overrides, key, fallback) {
+    var _a;
+    const raw = (_a = overrides === null || overrides === void 0 ? void 0 : overrides.ui) === null || _a === void 0 ? void 0 : _a[key];
+    if (typeof raw === 'string' && raw.length > 0) {
+        return clamp(raw, MAX_BUTTON_LABEL_CHARS);
+    }
+    return fallback;
+}
+/**
+ * Resolve the command-palette label for the tour command: admin
+ * override if set, otherwise the default supplied by the caller.
+ */
+export function commandLabel(overrides, fallback) {
+    var _a;
+    const raw = (_a = overrides === null || overrides === void 0 ? void 0 : overrides.command) === null || _a === void 0 ? void 0 : _a.label;
+    if (typeof raw === 'string' && raw.length > 0) {
+        return clamp(raw, MAX_COMMAND_LABEL_CHARS);
+    }
+    return fallback;
+}

package/lib/tour/tour-defaults.json

@@ -0,0 +1,58 @@
+{
+    "command": {
+        "label": "Show NBI tour"
+    },
+    "ui": {
+        "skip": "Skip tour",
+        "next": "Next",
+        "back": "Back",
+        "done": "Done"
+    },
+    "steps": {
+        "welcome": {
+            "title": "Welcome to Notebook Intelligence",
+            "description": "Your AI assistant lives in this sidebar. Take a quick tour of the settings, attachments, and chat modes so you can use it confidently."
+        },
+        "new-chat": {
+            "title": "Start a new chat",
+            "description": "Begin a fresh session when context gets crowded or you want to switch tasks."
+        },
+        "claude-history": {
+            "title": "Pick up where you left off",
+            "description": "Reopen an earlier Claude session from this workspace."
+        },
+        "settings-gear": {
+            "title": "Settings",
+            "description": "Configure providers, API keys, and extensions (MCP servers, skills, admin policies)."
+        },
+        "slash-commands": {
+            "title": "Run a slash command",
+            "description": "Open the menu for built-in commands and installed skills. Typing / at the start of the prompt does the same thing."
+        },
+        "add-context": {
+            "title": "Attach files as context",
+            "description": "Pin workspace files so the assistant can reference them. Typing @ in the prompt opens the same picker."
+        },
+        "upload-file": {
+            "title": "Upload from your computer",
+            "description": "Add files from outside the workspace. They're saved to the workspace and attached to this chat."
+        },
+        "drag-and-drop": {
+            "title": "Drag and drop",
+            "description": "Drag files from the JupyterLab file browser or your desktop onto the prompt. Keyboard users can attach the same files with the 'Attach files as context' and 'Upload from your computer' buttons."
+        },
+        "chat-mode": {
+            "title": "Pick a chat mode",
+            "description": "Ask is read-only and only answers questions. Agent can also run tools, such as file edits and shell commands."
+        },
+        "launcher-tiles": {
+            "title": "Run a coding agent in a terminal",
+            "description_singular": "The JupyterLab Launcher has a {launchers} tile in the 'Coding Agent' section. It opens a CLI session in a Jupyter terminal next to your notebook.",
+            "description_plural": "The JupyterLab Launcher has a 'Coding Agent' section with tiles for {launchers}. Each tile opens a CLI session in a Jupyter terminal next to your notebook."
+        },
+        "done": {
+            "title": "You're ready",
+            "description": "Try this: open a notebook and ask, 'Explain what this notebook does and suggest one improvement.' You can replay this tour anytime from the command palette."
+        }
+    }
+}

package/lib/tour/tour-events.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Decoupled trigger channel for the first-run tour.
+ *
+ * The JupyterLab command (`notebook-intelligence:show-tour`) is
+ * registered in `src/index.ts` so it shows up in the command palette
+ * and can be invoked from anywhere. The tour itself is rendered inside
+ * the chat sidebar (`src/chat-sidebar.tsx`) so it can access React
+ * state cleanly. Wiring those two together via DOM CustomEvents keeps
+ * index.ts free of any direct sidebar import and lets the tour be
+ * triggered from any future surface (a Settings dialog entry, a Help
+ * menu, a banner) by dispatching the same event.
+ *
+ * Dispatched on `document` to match the existing `copilotSidebar:*`
+ * channel convention elsewhere in this codebase.
+ */
+export declare const TOUR_START_EVENT = "nbi:show-tour";
+export declare const TOUR_STOP_EVENT = "nbi:hide-tour";
+export declare function dispatchShowTour(): void;
+export declare function dispatchHideTour(): void;

package/lib/tour/tour-events.js

@@ -0,0 +1,30 @@
+// Copyright (c) Mehmet Bektas <mbektasgh@outlook.com>
+/**
+ * Decoupled trigger channel for the first-run tour.
+ *
+ * The JupyterLab command (`notebook-intelligence:show-tour`) is
+ * registered in `src/index.ts` so it shows up in the command palette
+ * and can be invoked from anywhere. The tour itself is rendered inside
+ * the chat sidebar (`src/chat-sidebar.tsx`) so it can access React
+ * state cleanly. Wiring those two together via DOM CustomEvents keeps
+ * index.ts free of any direct sidebar import and lets the tour be
+ * triggered from any future surface (a Settings dialog entry, a Help
+ * menu, a banner) by dispatching the same event.
+ *
+ * Dispatched on `document` to match the existing `copilotSidebar:*`
+ * channel convention elsewhere in this codebase.
+ */
+export const TOUR_START_EVENT = 'nbi:show-tour';
+export const TOUR_STOP_EVENT = 'nbi:hide-tour';
+export function dispatchShowTour() {
+    if (typeof document === 'undefined') {
+        return;
+    }
+    document.dispatchEvent(new CustomEvent(TOUR_START_EVENT));
+}
+export function dispatchHideTour() {
+    if (typeof document === 'undefined') {
+        return;
+    }
+    document.dispatchEvent(new CustomEvent(TOUR_STOP_EVENT));
+}

package/lib/tour/tour-overlay.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="react" />
+interface ITourOverlayProps {
+    onClose: () => void;
+}
+export declare function TourOverlay(props: ITourOverlayProps): JSX.Element | null;
+export {};

package/lib/tour/tour-overlay.js

@@ -0,0 +1,350 @@
+// Copyright (c) Mehmet Bektas <mbektasgh@outlook.com>
+import React, { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { activeTourSteps } from './tour-steps';
+import { markTourCompleted } from './tour-state';
+import { NBIAPI } from '../api';
+import { uiLabel } from './tour-config';
+const TOOLTIP_GAP_PX = 12;
+const TOOLTIP_WIDTH_PX = 320;
+// Fallback used on the first render before the tooltip is measured.
+// Chosen to be larger than the typical rendered height so the initial
+// clamp errs toward staying on-screen rather than overshooting.
+const TOOLTIP_HEIGHT_FALLBACK_PX = 200;
+/**
+ * Compute the on-screen position of the tooltip given the anchor's
+ * bounding rect, the requested placement, and the tooltip's measured
+ * height. The clamp keeps the box fully on-screen even when the anchor
+ * sits near a viewport edge.
+ *
+ * Placement semantics: 'top' puts the tooltip above the anchor (its
+ * bottom edge gap-px above anchor.top), 'bottom' puts it below, 'left'
+ * to the left, 'right' to the right. The previous version omitted
+ * tooltip width/height from the top/left placements, which let the box
+ * overlap the anchor instead of sitting outside it.
+ */
+function computeTooltipPosition(anchorRect, placement, tooltipHeight) {
+    let top = 0;
+    let left = 0;
+    switch (placement) {
+        case 'top':
+            top = anchorRect.top - TOOLTIP_GAP_PX - tooltipHeight;
+            left = anchorRect.left + anchorRect.width / 2 - TOOLTIP_WIDTH_PX / 2;
+            break;
+        case 'bottom':
+            top = anchorRect.bottom + TOOLTIP_GAP_PX;
+            left = anchorRect.left + anchorRect.width / 2 - TOOLTIP_WIDTH_PX / 2;
+            break;
+        case 'left':
+            top = anchorRect.top + anchorRect.height / 2 - tooltipHeight / 2;
+            left = anchorRect.left - TOOLTIP_GAP_PX - TOOLTIP_WIDTH_PX;
+            break;
+        case 'right':
+            top = anchorRect.top + anchorRect.height / 2 - tooltipHeight / 2;
+            left = anchorRect.right + TOOLTIP_GAP_PX;
+            break;
+    }
+    // Clamp inside the viewport with an 8px margin so the tooltip never
+    // disappears off-screen near the edges. The vertical clamp accounts
+    // for tooltip height so the bottom edge stays visible even when the
+    // anchor is near the bottom of the viewport.
+    const margin = 8;
+    left = Math.max(margin, Math.min(left, window.innerWidth - TOOLTIP_WIDTH_PX - margin));
+    top = Math.max(margin, Math.min(top, window.innerHeight - tooltipHeight - margin));
+    return { top, left };
+}
+function findAnchor(anchorId) {
+    if (!anchorId) {
+        return null;
+    }
+    return document.querySelector(`[data-tour-id="${anchorId}"]`);
+}
+export function TourOverlay(props) {
+    // Compute the list of steps once. Capabilities can change at runtime
+    // (e.g. user switches Claude mode mid-tour) but recomputing the list
+    // mid-flight would change indices under the user; freeze on mount.
+    const steps = useMemo(() => activeTourSteps(), []);
+    // Freeze the admin overrides snapshot at mount, alongside `steps`, so
+    // a config push mid-tour doesn't relabel the active overlay's buttons.
+    const labels = useMemo(() => {
+        const overrides = NBIAPI.config.tourOverrides;
+        return {
+            skip: uiLabel(overrides, 'skip', 'Skip tour'),
+            next: uiLabel(overrides, 'next', 'Next'),
+            back: uiLabel(overrides, 'back', 'Back'),
+            done: uiLabel(overrides, 'done', 'Done')
+        };
+    }, []);
+    const [index, setIndex] = useState(0);
+    const [anchorRect, setAnchorRect] = useState(null);
+    const [tooltipHeight, setTooltipHeight] = useState(TOOLTIP_HEIGHT_FALLBACK_PX);
+    const tooltipRef = useRef(null);
+    const rootRef = useRef(null);
+    const previouslyFocusedRef = useRef(null);
+    const step = steps[index];
+    // Save focus on mount, restore on unmount. Pairs with the focus trap
+    // below so the tour leaves focus where it found it (e.g. the prompt
+    // textarea) instead of dumping the user to document.body.
+    useEffect(() => {
+        var _a;
+        previouslyFocusedRef.current =
+            (_a = document.activeElement) !== null && _a !== void 0 ? _a : null;
+        return () => {
+            const prev = previouslyFocusedRef.current;
+            if (prev && document.contains(prev) && typeof prev.focus === 'function') {
+                prev.focus();
+            }
+        };
+    }, []);
+    // Measure the tooltip *before* paint so the next frame clamps its
+    // position against the actual rendered height. useLayoutEffect (not
+    // useEffect) prevents the user seeing a frame at the fallback height.
+    // Re-measure only on step change so a no-op render doesn't pay the
+    // getBoundingClientRect tax.
+    useLayoutEffect(() => {
+        if (!tooltipRef.current) {
+            return;
+        }
+        const h = tooltipRef.current.getBoundingClientRect().height;
+        if (h && Math.abs(h - tooltipHeight) > 0.5) {
+            setTooltipHeight(h);
+        }
+        // tooltipHeight intentionally omitted from deps: this effect only
+        // re-runs on step change and the > 0.5px guard already prevents
+        // infinite loops if measurement converges.
+    }, [step === null || step === void 0 ? void 0 : step.id, index]);
+    // Resolve the anchor synchronously before the next paint. If the
+    // anchor isn't in the DOM yet (parent React tree may not have
+    // committed), retry across a handful of animation frames before
+    // giving up; missing anchors auto-advance so the user doesn't land
+    // on a blank step. useLayoutEffect on the synchronous path
+    // eliminates the one-frame "wrong position" flash on step change.
+    useLayoutEffect(() => {
+        if (!step) {
+            return;
+        }
+        if (!step.anchorId) {
+            setAnchorRect(null);
+            return;
+        }
+        // Clear the stale rect from the previous step immediately so a
+        // late paint never shows the spotlight in the old position.
+        setAnchorRect(null);
+        let rafId = 0;
+        let attempts = 0;
+        const MAX_ATTEMPTS = 10;
+        let removeListeners = () => { };
+        const tryResolve = () => {
+            const anchor = findAnchor(step.anchorId);
+            if (anchor) {
+                const updateRect = () => setAnchorRect(anchor.getBoundingClientRect());
+                updateRect();
+                window.addEventListener('resize', updateRect);
+                window.addEventListener('scroll', updateRect, true);
+                removeListeners = () => {
+                    window.removeEventListener('resize', updateRect);
+                    window.removeEventListener('scroll', updateRect, true);
+                };
+                return;
+            }
+            attempts += 1;
+            if (attempts >= MAX_ATTEMPTS) {
+                // Genuinely missing; auto-advance so the user doesn't land on a
+                // blank step.
+                setIndex(i => i + 1);
+                return;
+            }
+            rafId = requestAnimationFrame(tryResolve);
+        };
+        // Attempt the first resolve synchronously so a happy path step
+        // change paints in the right place on the very next frame.
+        tryResolve();
+        return () => {
+            cancelAnimationFrame(rafId);
+            removeListeners();
+        };
+    }, [step === null || step === void 0 ? void 0 : step.anchorId, index]);
+    // Stable callback refs so the keydown handler can stay bound for the
+    // overlay's lifetime without re-binding per step. Closing over `index`
+    // directly would make the deps load-bearing in a non-obvious way.
+    const advanceRef = useRef(() => { });
+    const backRef = useRef(() => { });
+    const finishRef = useRef(() => { });
+    // Keyboard nav: Esc dismisses, Enter / Right advance, Left back.
+    // Tab/Shift-Tab are trapped inside the dialog (paired with
+    // aria-modal="true" so screen readers' modal semantics match reality).
+    // Ignore key presses targeted at editable elements so the prompt
+    // textarea's history-nav arrow keys still work if focus somehow
+    // landed there before the tour mounted.
+    useEffect(() => {
+        const handler = (e) => {
+            const target = e.target;
+            const inEditable = !!target &&
+                (target.tagName === 'INPUT' ||
+                    target.tagName === 'TEXTAREA' ||
+                    target.isContentEditable);
+            // Tab/Shift-Tab focus trap is enforced even when target is an
+            // editable element so focus can't escape the dialog through the
+            // textarea below it.
+            if (e.key === 'Tab') {
+                const root = rootRef.current;
+                if (!root) {
+                    return;
+                }
+                const focusables = Array.from(root.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])')).filter(el => !el.hasAttribute('disabled'));
+                if (focusables.length === 0) {
+                    return;
+                }
+                const first = focusables[0];
+                const last = focusables[focusables.length - 1];
+                const active = document.activeElement;
+                // If focus is outside the dialog entirely (e.g. clicked through
+                // the scrim somehow), pull it back to the first focusable.
+                if (!active || !root.contains(active)) {
+                    e.preventDefault();
+                    first.focus();
+                    return;
+                }
+                if (e.shiftKey && active === first) {
+                    e.preventDefault();
+                    last.focus();
+                }
+                else if (!e.shiftKey && active === last) {
+                    e.preventDefault();
+                    first.focus();
+                }
+                return;
+            }
+            if (inEditable) {
+                return;
+            }
+            if (e.key === 'Escape') {
+                e.preventDefault();
+                finishRef.current();
+            }
+            else if (e.key === 'ArrowRight' || e.key === 'Enter') {
+                e.preventDefault();
+                advanceRef.current();
+            }
+            else if (e.key === 'ArrowLeft') {
+                e.preventDefault();
+                backRef.current();
+            }
+        };
+        window.addEventListener('keydown', handler);
+        return () => window.removeEventListener('keydown', handler);
+    }, []);
+    // If we run out of steps (e.g. every anchor disappeared) close the
+    // tour on the next tick rather than calling setState inside the
+    // render below.
+    useEffect(() => {
+        if (!step) {
+            finish();
+        }
+    }, [step]);
+    const advance = () => {
+        if (index >= steps.length - 1) {
+            finish();
+            return;
+        }
+        setIndex(i => i + 1);
+    };
+    const back = () => {
+        if (index > 0) {
+            setIndex(i => i - 1);
+        }
+    };
+    const finish = () => {
+        markTourCompleted();
+        props.onClose();
+    };
+    // Refresh the callback refs every render so the keydown listener
+    // (bound once) always reads the latest closures.
+    advanceRef.current = advance;
+    backRef.current = back;
+    finishRef.current = finish;
+    if (!step) {
+        // No step to render right now. The cleanup effect above will fire
+        // `finish()` on the next tick; in the meantime return null so
+        // React doesn't see a setState inside this render path.
+        return null;
+    }
+    const isCenter = step.placement === 'center' || !step.anchorId;
+    // Anchored steps are "ready" once we have measured the anchor for
+    // *this* step. While unmeasured we keep the dialog mounted but
+    // visually hidden so the user doesn't see a flash at the centered
+    // fallback position before the real position lands.
+    const measured = isCenter || anchorRect !== null;
+    const tooltipStyle = isCenter
+        ? {
+            top: '50%',
+            left: '50%',
+            transform: 'translate(-50%, -50%)',
+            width: TOOLTIP_WIDTH_PX
+        }
+        : (() => {
+            // Fall back to a zero-size rect at the viewport center when the
+            // anchor hasn't been measured yet. `DOMRect` is the standard
+            // constructor in the browser; jsdom-only test environments
+            // sometimes lack it, so build a plain object that satisfies
+            // the fields `computeTooltipPosition` reads.
+            const rect = anchorRect !== null && anchorRect !== void 0 ? anchorRect : {
+                top: window.innerHeight / 2,
+                left: window.innerWidth / 2,
+                right: window.innerWidth / 2,
+                bottom: window.innerHeight / 2,
+                width: 0,
+                height: 0,
+                x: window.innerWidth / 2,
+                y: window.innerHeight / 2,
+                toJSON: () => ({})
+            };
+            // step.placement is guaranteed not to be 'center' here (isCenter
+            // would have been true otherwise); narrow for the type checker.
+            const placement = step.placement;
+            return {
+                ...computeTooltipPosition(rect, placement, tooltipHeight),
+                width: TOOLTIP_WIDTH_PX,
+                visibility: measured ? 'visible' : 'hidden'
+            };
+        })();
+    const spotlight = !isCenter && anchorRect && (React.createElement("div", { className: "nbi-tour-spotlight", style: {
+            top: anchorRect.top - 4,
+            left: anchorRect.left - 4,
+            width: anchorRect.width + 8,
+            height: anchorRect.height + 8
+        } }));
+    const isLast = index === steps.length - 1;
+    const progress = ((index + 1) / steps.length) * 100;
+    // Render into document.body via portal so the overlay can extend
+    // outside the sidebar's clip region and float over the rest of
+    // JupyterLab.
+    // ARIA: the dialog is modal-ish (covers the UI), so flag it as such.
+    // The label / description IDs change per step, but most screen
+    // readers don't re-announce when those attrs change without remount.
+    // The step body is wrapped in an aria-live="polite" region so each
+    // transition is announced as the content changes.
+    const titleId = `nbi-tour-title-${step.id}`;
+    const descId = `nbi-tour-desc-${step.id}`;
+    // Arrow direction is the inverse of placement (a tooltip placed
+    // ABOVE the anchor has its tail pointing DOWN). Center-placement
+    // tooltips have no anchor, so no arrow.
+    const arrowDirection = isCenter ? null : step.placement;
+    return createPortal(React.createElement("div", { ref: rootRef, className: "nbi-tour-root", role: "dialog", "aria-modal": "true", "aria-labelledby": titleId, "aria-describedby": descId },
+        React.createElement("div", { className: "nbi-tour-scrim" }),
+        spotlight,
+        React.createElement("div", { ref: tooltipRef, className: `nbi-tour-tooltip${isCenter ? ' nbi-tour-tooltip-center' : ''}`, style: tooltipStyle },
+            arrowDirection && (React.createElement("div", { className: `nbi-tour-arrow nbi-tour-arrow-${arrowDirection}`, "aria-hidden": "true" })),
+            React.createElement("div", { className: "nbi-tour-progress", role: "progressbar", "aria-valuemin": 1, "aria-valuemax": steps.length, "aria-valuenow": index + 1, "aria-label": `Tour progress: step ${index + 1} of ${steps.length}` },
+                React.createElement("div", { className: "nbi-tour-progress-bar", style: { width: `${progress}%` } })),
+            React.createElement("div", { className: "nbi-tour-body", "aria-live": "polite", "aria-atomic": "true", key: step.id },
+                React.createElement("div", { className: "nbi-tour-title", id: titleId }, step.title),
+                React.createElement("div", { className: "nbi-tour-description", id: descId }, step.description)),
+            React.createElement("div", { className: "nbi-tour-actions" },
+                React.createElement("button", { type: "button", className: "nbi-tour-skip-link", onClick: finish }, labels.skip),
+                React.createElement("div", { style: { flexGrow: 1 } }),
+                index > 0 && (React.createElement("button", { type: "button", className: "jp-Dialog-button jp-mod-reject jp-mod-styled", onClick: back },
+                    React.createElement("div", { className: "jp-Dialog-buttonLabel" }, labels.back))),
+                React.createElement("button", { type: "button", className: "jp-Dialog-button jp-mod-accept jp-mod-styled", onClick: advance, autoFocus: true },
+                    React.createElement("div", { className: "jp-Dialog-buttonLabel" }, isLast ? labels.done : labels.next))))), document.body);
+}

package/lib/tour/tour-state.d.ts

@@ -0,0 +1,20 @@
+/**
+ * localStorage-backed persistence for the first-run tour.
+ *
+ * The tour is shown exactly once per browser per major tour version. The
+ * version is bumped (in code) whenever the step set changes meaningfully
+ * so existing users get re-prompted instead of silently missing new
+ * onboarding content. Users can also re-run the tour on demand via the
+ * `notebook-intelligence:show-tour` command, which calls `resetTour()`.
+ *
+ * Why localStorage and not server-side state: the tour is purely UI; a
+ * round trip to the Jupyter server on every sidebar mount just to check
+ * a single flag would add latency to a hot path. localStorage is
+ * per-browser, which is the right granularity (a user signing in on a
+ * second browser benefits from seeing the tour again).
+ */
+export declare const TOUR_VERSION = 1;
+export declare const TOUR_STORAGE_KEY = "nbi.tour.completed";
+export declare function hasCompletedTour(): boolean;
+export declare function markTourCompleted(): void;
+export declare function resetTour(): void;