@theoremjs/studio 0.0.0-stage → 0.3.2

package/ui/studio-settings.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from 'react';
+import type { ProjectSession } from './lib/studio-project.ts';
+/** The door to Settings at the foot of the shell's rail. Nothing shows until a screen can open them. */
+export declare function SettingsRailButton(): import("react").JSX.Element | null;
+/** Watching the project's files: absent when the studio command was started without it. */
+export interface WatchChoice {
+    on: boolean;
+    set: (on: boolean) => void;
+}
+/** Whether changing a shared value asks first, as the store holds it. */
+export interface SharedAsking {
+    asks: boolean;
+    set: (asks: boolean) => void;
+}
+/** What the Project section can do to this tab; an action is absent when there is nothing for it to do. */
+export interface TabActions {
+    clearChats: () => void;
+    discard: (() => void) | undefined;
+}
+export interface StudioSettingsProps {
+    project: ProjectSession;
+    /** The `@theoremjs/agents` version the studio runs. */
+    version: string;
+    watch: WatchChoice | undefined;
+    shared: SharedAsking;
+    actions: TabActions;
+    /** The key slots, as the studio's Keys panel shows them. */
+    keys: ReactNode;
+}
+/** Settings, inside the studio's panel: the panel widens over the preview to hold them. */
+export declare function StudioSettings(props: StudioSettingsProps): import("react").JSX.Element;

package/ui/studio-settings.js

@@ -0,0 +1,288 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Settings for the studio open on a project: where every choice about how the studio behaves is
+ * made. Choices are kept in this browser, keys in this tab, and nothing is written to the project.
+ */
+import { AlertDialog } from '@astryxdesign/core/AlertDialog';
+import { Button } from '@astryxdesign/core/Button';
+import { CheckboxInput } from '@astryxdesign/core/CheckboxInput';
+import { Divider } from '@astryxdesign/core/Divider';
+import { Field } from '@astryxdesign/core/Field';
+import { Grid } from '@astryxdesign/core/Grid';
+import { Heading } from '@astryxdesign/core/Heading';
+import { HStack } from '@astryxdesign/core/HStack';
+import { useMediaQuery } from '@astryxdesign/core/hooks';
+import { Icon } from '@astryxdesign/core/Icon';
+import { IconButton } from '@astryxdesign/core/IconButton';
+import { Layout, LayoutContent } from '@astryxdesign/core/Layout';
+import { MetadataList, MetadataListItem } from '@astryxdesign/core/MetadataList';
+import { RadioList, RadioListItem } from '@astryxdesign/core/RadioList';
+import { Section } from '@astryxdesign/core/Section';
+import { SegmentedControl, SegmentedControlItem } from '@astryxdesign/core/SegmentedControl';
+import { StackItem } from '@astryxdesign/core/Stack';
+import { Tab, TabList } from '@astryxdesign/core/TabList';
+import { Text } from '@astryxdesign/core/Text';
+import { TreeList } from '@astryxdesign/core/TreeList';
+import { Typeahead } from '@astryxdesign/core/Typeahead';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconBrandVscode, IconDeviceDesktopCode, IconPlus, IconSearch, IconSettings, IconX, } from '@tabler/icons-react';
+import { useEffect, useId, useState } from 'react';
+import { editorLabel, STUDIO_EDITORS } from "../editors.js";
+import { IconCursor } from "./brand-icons.js";
+import { freshPerson, listPeople, useActingAs } from "./lib/acting-as.js";
+import { setPref, usePref } from "./lib/studio-prefs.js";
+import { closeSettings, openSettings, SETTINGS_SECTIONS, showSettingsSection, useSettingsDoor, } from "./lib/studio-settings.js";
+import { NAV_WIDTH } from "./studio-nav.js";
+const SECTION_LABELS = {
+    files: 'Files',
+    confirmations: 'Confirmations',
+    keys: 'Keys',
+    people: 'People',
+    project: 'Project',
+    about: 'About',
+};
+/** Every setting by name, for the search: choosing one opens its section. `words` is what else a builder might type. */
+const SETTINGS = [
+    {
+        id: 'editor',
+        label: 'Open files in',
+        section: 'files',
+        words: 'editor automatic vs code vscode cursor',
+    },
+    { id: 'watch', label: 'Watch files', section: 'files', words: 'reload save' },
+    { id: 'files-toast', label: 'Tell me when files change', section: 'files', words: 'note notify' },
+    {
+        id: 'ask-shared',
+        label: 'Ask before changing a shared value',
+        section: 'confirmations',
+        words: 'confirm asking',
+    },
+    {
+        id: 'ask-writes',
+        label: 'Ask before a tool writes',
+        section: 'confirmations',
+        words: 'confirm asking destructive run',
+    },
+    { id: 'keys', label: 'Model keys', section: 'keys', words: 'api key provider' },
+    {
+        id: 'acting-as',
+        label: 'Who a run acts as',
+        section: 'people',
+        words: 'person user account place sign in',
+    },
+    { id: 'open-project', label: 'Open project and setup file', section: 'project' },
+    {
+        id: 'clear-chats',
+        label: "Clear this tab's chats",
+        section: 'project',
+        words: 'conversation reset',
+    },
+    { id: 'discard', label: 'Discard unsaved edits', section: 'project', words: 'revert reset' },
+    { id: 'version', label: 'Package version', section: 'about' },
+    { id: 'address', label: 'Studio address', section: 'about', words: 'url port server' },
+];
+const settingsSource = {
+    search: (query) => {
+        const asked = query.toLowerCase();
+        return SETTINGS.filter((setting) => `${setting.label} ${setting.words ?? ''}`.toLowerCase().includes(asked));
+    },
+    bootstrap: () => [...SETTINGS],
+};
+/** The door to Settings at the foot of the shell's rail. Nothing shows until a screen can open them. */
+export function SettingsRailButton() {
+    const door = useSettingsDoor();
+    if (!door.ready)
+        return null;
+    return (_jsx(IconButton, { label: "Settings", variant: "ghost", size: "lg", icon: _jsx(Icon, { icon: IconSettings }), tooltip: door.open ? 'Back to the studio' : 'Settings', "aria-pressed": door.open, onClick: () => {
+            if (door.open)
+                closeSettings();
+            else
+                openSettings();
+        } }));
+}
+/** One group of settings: what it is about on the left, its controls on the right. Titled as the editor titles a section. */
+function Group({ title, about, children }) {
+    return (_jsxs(Grid, { columns: { minWidth: 320 }, gap: 10, children: [_jsxs(VStack, { gap: 1, children: [_jsx(Text, { type: "label", weight: "semibold", children: title }), _jsx(Text, { type: "supporting", color: "secondary", children: about })] }), _jsx(VStack, { gap: 5, children: children })] }));
+}
+const AUTOMATIC = 'automatic';
+/** Where files open: the studio's own pick, or one of the two editors Settings offers. */
+const EDITOR_CHOICES = [
+    { value: AUTOMATIC, label: 'Automatic', icon: IconDeviceDesktopCode },
+    ...STUDIO_EDITORS.filter((editor) => editor.choice).map((editor) => ({
+        value: editor.command,
+        label: editor.label,
+        icon: editor.command === 'cursor' ? IconCursor : IconBrandVscode,
+    })),
+];
+/** What Automatic opens files in, in the builder's words. */
+function automaticNote(automatic) {
+    return automatic
+        ? `Automatic opens ${editorLabel(automatic)}.`
+        : 'Automatic opens the editor the studio was started with.';
+}
+function EditorChoice({ automatic }) {
+    const editor = usePref('editor');
+    const id = useId();
+    return (_jsx(Field, { label: "Open files in", description: automaticNote(automatic), inputID: id, isGroupLabel: true, children: _jsx(SegmentedControl, { label: "Open files in", size: "sm", value: editor || AUTOMATIC, onChange: (next) => {
+                setPref('editor', next === AUTOMATIC ? '' : next);
+            }, children: EDITOR_CHOICES.map((choice) => (_jsx(SegmentedControlItem, { value: choice.value, label: choice.label, icon: _jsx(Icon, { icon: choice.icon, size: "sm" }) }, choice.value))) }) }));
+}
+function FilesSettings({ project, watch, }) {
+    const filesToast = usePref('filesToast');
+    return (_jsxs(_Fragment, { children: [_jsx(Group, { title: "Your editor", about: "Where a file opens when you follow a setting to the line that sets it.", children: _jsx(EditorChoice, { automatic: project.editor }) }), _jsx(Divider, {}), _jsxs(Group, { title: "Changes from your files", about: "What the studio does when your editor saves a file your setup reads.", children: [_jsx(CheckboxInput, { label: "Watch files", description: "Take in what your editor saves, as it saves. Your unsaved studio edits are kept.", value: watch?.on ?? false, isDisabled: !watch, disabledMessage: "The studio command was started with --no-watch.", onChange: (on) => watch?.set(on) }), _jsx(CheckboxInput, { label: "Tell me when files change", description: "A short note each time a save in your editor changed a setting here.", value: filesToast === 'on', onChange: (on) => {
+                            setPref('filesToast', on ? 'on' : 'off');
+                        } })] })] }));
+}
+const isAskWrites = (value) => value === 'always' || value === 'destructive';
+function ConfirmationSettings({ shared }) {
+    const askWrites = usePref('askWrites');
+    return (_jsxs(_Fragment, { children: [_jsx(Group, { title: "Shared values", about: "A value several agents share changes on every one of them.", children: _jsx(CheckboxInput, { label: "Ask before changing a shared value", description: "Shows which agents and files the change reaches, before it is made.", value: shared.asks, onChange: shared.set }) }), _jsx(Divider, {}), _jsx(Group, { title: "Tools that write", about: "A real run of a tool that writes can change something outside the studio.", children: _jsxs(RadioList, { label: "Ask before a run", value: askWrites, onChange: (next) => {
+                        if (isAskWrites(next))
+                            setPref('askWrites', next);
+                    }, children: [_jsx(RadioListItem, { value: "always", label: "Every tool that writes", description: "Shows the input the run would send, each time." }), _jsx(RadioListItem, { value: "destructive", label: "Only destructive tools", description: "Tools that read and write run straight away. Tools marked destructive still ask." })] }) })] }));
+}
+const NO_ONE = 'no-one';
+const personValue = (person) => `person:${person.id}`;
+function PlacePicker({ offer, place, onChange, }) {
+    return (_jsx(SegmentedControl, { label: "Place", size: "sm", value: place, onChange: onChange, children: offer.places.map((each) => (_jsx(SegmentedControlItem, { value: each.id, label: each.label }, each.id))) }));
+}
+/** What went wrong, in the words it was said in. */
+const said = (error) => (error instanceof Error ? error.message : String(error));
+/** The people in a place, as the setup file answers them, and what it said when it could not. */
+function usePeopleIn(project, offer, place) {
+    const [found, setFound] = useState();
+    useEffect(() => {
+        if (!offer.existing)
+            return;
+        let isCurrent = true;
+        listPeople(project, place).then((people) => {
+            if (isCurrent)
+                setFound({ place, people });
+        }, (error) => {
+            if (isCurrent)
+                setFound({ place, people: [], error: said(error) });
+        });
+        return () => {
+            isCurrent = false;
+        };
+    }, [project, offer.existing, place]);
+    return found?.place === place ? found : undefined;
+}
+/** A new person the setup makes in a place, picked as soon as it is made; and what it said when it could not. */
+function useFreshPerson(project) {
+    const { choose } = useActingAs();
+    const [made, setMade] = useState([]);
+    const [making, setMaking] = useState();
+    const make = (place) => {
+        setMaking({ place });
+        freshPerson(project, place).then((person) => {
+            setMade((before) => [...before, { place, person }]);
+            setMaking(undefined);
+            choose({ place, person });
+        }, (error) => {
+            setMaking({ place, error: said(error) });
+        });
+    };
+    return { made, making, make };
+}
+/** The people to offer in a place: the ones the setup listed, then any picked or made here it did not. */
+function shownPeople(place, listed, actingAs, made) {
+    const shown = [...listed];
+    const here = [...(actingAs ? [actingAs] : []), ...made].filter((each) => each.place === place);
+    for (const { person } of here)
+        if (!shown.some((each) => each.id === person.id))
+            shown.push(person);
+    return shown;
+}
+/** The radio the pick shows as in a place: no one, its person, or none when the person is elsewhere. */
+function pickedIn(place, actingAs) {
+    if (!actingAs)
+        return NO_ONE;
+    return actingAs.place === place ? personValue(actingAs.person) : '';
+}
+function PersonList({ place, shown }) {
+    const { actingAs, choose } = useActingAs();
+    return (_jsxs(RadioList, { label: "Person", value: pickedIn(place, actingAs), onChange: (next) => {
+            if (next === NO_ONE)
+                choose(undefined);
+            const person = shown.find((each) => personValue(each) === next);
+            if (person)
+                choose({ place, person });
+        }, children: [_jsx(RadioListItem, { value: NO_ONE, label: "No one", description: "Runs act for no one." }), shown.map((person) => (_jsx(RadioListItem, { value: personValue(person), label: person.label, description: _jsx(Text, { type: "supporting", color: "secondary", maxLines: 1, hasTruncateTooltip: "end", children: person.id }) }, person.id)))] }));
+}
+function Muted({ children }) {
+    return (_jsx(Text, { type: "supporting", color: "secondary", children: children }));
+}
+function PeoplePicker({ project, offer }) {
+    const { actingAs } = useActingAs();
+    const [place, setPlace] = useState(actingAs?.place ?? offer.places[0]?.id ?? '');
+    const placeId = useId();
+    const found = usePeopleIn(project, offer, place);
+    const fresh = useFreshPerson(project);
+    const makingHere = fresh.making?.place === place ? fresh.making : undefined;
+    const error = found?.error ?? makingHere?.error;
+    return (_jsxs(_Fragment, { children: [_jsx(Field, { label: "Place", description: "Where the people your app names live.", inputID: placeId, isGroupLabel: true, children: _jsx(PlacePicker, { offer: offer, place: place, onChange: setPlace }) }), _jsx(PersonList, { place: place, shown: shownPeople(place, found?.people ?? [], actingAs, fresh.made) }), offer.existing && !found && _jsx(Muted, { children: "Finding the people here\u2026" }), offer.fresh && (_jsx(HStack, { children: _jsx(Button, { label: "New person", variant: "secondary", icon: _jsx(Icon, { icon: IconPlus, size: "sm" }), isDisabled: makingHere !== undefined && makingHere.error === undefined, onClick: () => {
+                        fresh.make(place);
+                    } }) })), error && _jsx(Muted, { children: error })] }));
+}
+function PeopleSettings({ project }) {
+    const { offer, problem } = useActingAs();
+    return (_jsx(Group, { title: "Who a run acts as", about: "Your app's tools act for this person. Your setup file names the places and the people, and makes new ones.", children: offer ? (_jsx(PeoplePicker, { project: project, offer: offer })) : (_jsx(Muted, { children: problem ?? 'Your setup file offers no people, so every run acts as no one.' })) }));
+}
+function ProjectSettings({ project, actions }) {
+    const [clearing, setClearing] = useState(false);
+    return (_jsxs(_Fragment, { children: [_jsx(Group, { title: "Open project", about: "What the studio command opened. The studio reads it from your files.", children: _jsxs(MetadataList, { children: [_jsx(MetadataListItem, { label: "Project", children: project.name }), project.setup && _jsx(MetadataListItem, { label: "Setup file", children: project.setup }), _jsx(MetadataListItem, { label: "Agents", children: String(project.profiles.length) })] }) }), _jsx(Divider, {}), _jsxs(Group, { title: "This tab", about: "What this tab holds that your files do not.", children: [_jsxs(VStack, { gap: 1, children: [_jsx(HStack, { children: _jsx(Button, { label: "Clear this tab's chats", variant: "secondary", onClick: () => {
+                                        setClearing(true);
+                                    } }) }), _jsx(Text, { type: "supporting", color: "secondary", children: "Every agent's preview conversation starts again." })] }), _jsxs(VStack, { gap: 1, children: [_jsx(HStack, { children: _jsx(Button, { label: "Discard unsaved edits", variant: "secondary", isDisabled: !actions.discard, onClick: actions.discard }) }), _jsx(Text, { type: "supporting", color: "secondary", children: actions.discard
+                                    ? 'The studio opens your files as they are. Undo brings the edits back.'
+                                    : 'Nothing here differs from your files.' })] })] }), _jsx(AlertDialog, { isOpen: clearing, onOpenChange: setClearing, title: "Clear this tab's chats?", description: "Every agent's preview conversation in this tab is removed. This can't be undone.", actionLabel: "Clear chats", actionVariant: "destructive", onAction: () => {
+                    actions.clearChats();
+                    setClearing(false);
+                } })] }));
+}
+function AboutSettings({ project, version }) {
+    return (_jsx(Group, { title: "This studio", about: "Settings are kept in this browser. Keys stay in this tab. Neither is written to your project.", children: _jsxs(MetadataList, { children: [_jsx(MetadataListItem, { label: "Package", children: `@theoremjs/agents ${version}` }), _jsx(MetadataListItem, { label: "Studio address", children: `${location.origin}/studio/` }), _jsx(MetadataListItem, { label: "Project server", children: new URL(project.endpoint, location.href).origin })] }) }));
+}
+function SectionBody({ section, ...props }) {
+    switch (section) {
+        case 'files':
+            return _jsx(FilesSettings, { project: props.project, watch: props.watch });
+        case 'confirmations':
+            return _jsx(ConfirmationSettings, { shared: props.shared });
+        case 'keys':
+            return (_jsx(Group, { title: "Model keys", about: "Your own keys, to run an agent with. Never saved, never written to your project.", children: props.keys }));
+        case 'people':
+            return _jsx(PeopleSettings, { project: props.project });
+        case 'project':
+            return _jsx(ProjectSettings, { project: props.project, actions: props.actions });
+        default:
+            return _jsx(AboutSettings, { project: props.project, version: props.version });
+    }
+}
+const isSection = (value) => SETTINGS_SECTIONS.includes(value);
+/** The nav's head, as the studio's tree and the docs head theirs: the name, what is open, then the search. */
+function SettingsNavHead({ project, version }) {
+    return (_jsxs(VStack, { gap: 4, children: [_jsxs(VStack, { gap: 1, children: [_jsx(Heading, { level: 3, children: "theorem studio" }), _jsx(Text, { type: "supporting", color: "secondary", children: `${project.name} · @theoremjs/agents ${version}` })] }), _jsx(Typeahead, { label: "Search", isLabelHidden: true, placeholder: "Search settings...", searchSource: settingsSource, value: null, onChange: (item) => {
+                    const found = SETTINGS.find((setting) => setting.id === item?.id);
+                    if (found)
+                        showSettingsSection(found.section);
+                }, hasEntriesOnFocus: true, startIcon: IconSearch })] }));
+}
+/** The widest the settings grow, so a wide screen does not stretch a row across it. */
+const SETTINGS_WIDTH = '72rem';
+/** Settings, inside the studio's panel: the panel widens over the preview to hold them. */
+export function StudioSettings(props) {
+    const isNarrow = useMediaQuery('(max-width: 768px)');
+    const { section } = useSettingsDoor();
+    return (_jsx(Section, { variant: "transparent", height: "100%", padding: 0, children: _jsx(Layout, { height: "fill", start: isNarrow ? undefined : (_jsx(Section, { variant: "transparent", width: NAV_WIDTH, height: "100%", padding: 4, dividers: ['end'], children: _jsxs(VStack, { gap: 4, height: "100%", children: [_jsx(SettingsNavHead, { project: props.project, version: props.version }), _jsx(TreeList, { className: "studio-settings-tree", density: "compact", "aria-label": "Settings", items: SETTINGS_SECTIONS.map((each) => ({
+                                id: each,
+                                label: SECTION_LABELS[each],
+                                isSelected: section === each,
+                                onClick: () => {
+                                    showSettingsSection(each);
+                                },
+                            })) })] }) })), content: _jsxs(LayoutContent, { padding: 0, children: [_jsx(Section, { variant: "transparent", padding: 3, dividers: ['bottom'], children: _jsxs(HStack, { gap: 2, vAlign: "center", children: [_jsx(StackItem, { size: "fill", children: _jsx(Heading, { level: 4, maxLines: 1, children: SECTION_LABELS[section] }) }), _jsx(IconButton, { label: "Close settings", variant: "ghost", icon: _jsx(Icon, { icon: IconX, size: "sm" }), tooltip: "Back to the studio", onClick: closeSettings })] }) }), _jsx(Section, { variant: "transparent", padding: 3, maxWidth: SETTINGS_WIDTH, className: "studio-settings-body", children: _jsxs(VStack, { gap: 4, children: [isNarrow && _jsx(SettingsNavHead, { project: props.project, version: props.version }), isNarrow && (_jsx(VStack, { hAlign: "center", children: _jsx(TabList, { value: section, onChange: (next) => {
+                                            if (isSection(next))
+                                                showSettingsSection(next);
+                                        }, children: SETTINGS_SECTIONS.map((each) => (_jsx(Tab, { value: each, label: SECTION_LABELS[each] }, each))) }) })), _jsx(SectionBody, { section: section, ...props })] }) })] }) }) }));
+}

package/ui/studio-shell.css

@@ -0,0 +1,27 @@
+/*
+ * A panel scrolls in Astryx's ScrollableArea. Its content box is at least as
+ * tall as the scrollport, so a short body leaves an empty stretch under the
+ * rows. Nothing in a panel needs that minimum. The :not(#) chain is how
+ * Astryx locks the minimum; the class has to match it to let the box size to
+ * the rows.
+ */
+.theorem-panel-scroll [data-scroll-content]:not(#\#):not(#\#):not(#\#):not(#\#) {
+  min-height: auto;
+}
+
+/* The rail is inline at md and up. Only when it yields to the drawer
+   should the page take the same start inset as top and right. */
+@media (width < 768px) {
+  [role="main"] {
+    margin-inline-start: var(--spacing-4);
+    width: calc(100% - 2 * var(--spacing-4));
+  }
+}
+
+/* A dialog sits in the top layer, above the rail and the screen's edge. Insetting it to the shell's
+   page (see ShellBounds) centres it there. Menus and pickers are left to Astryx: an inset moves
+   them off the field they open under. */
+dialog:modal {
+  inset: var(--shell-top, 0px) var(--shell-right, 0px) var(--shell-bottom, 0px)
+    var(--shell-left, 0px);
+}

package/ui/studio-shell.d.ts

@@ -0,0 +1,43 @@
+import { type DefinedTheme } from '@astryxdesign/core/theme';
+import { type ReactNode, type SVGProps } from 'react';
+import { type PackageLinks } from './studio-nav.ts';
+/**
+ * JSR brand mark (from jsr.io's icon), filled in the current colour. It spans the
+ * full 24-unit box, as Tabler's brand-npm does with its stroke, so Astryx's icon
+ * sizing sets both at the same visual size.
+ */
+declare function IconJsr(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
+/** The icon each of the rail's rows carries, by its label. */
+export declare const PAGE_ICONS: {
+    readonly Studio: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    readonly Docs: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+};
+export declare const PACKAGE_ICONS: {
+    readonly GitHub: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+    readonly JSR: typeof IconJsr;
+    readonly npm: import("react").ForwardRefExoticComponent<import("@tabler/icons-react").IconProps & import("react").RefAttributes<SVGSVGElement>>;
+};
+export interface StudioRailProps {
+    /** The theme the page is drawn in. The rail is always its dark mode, so its icons read on black. */
+    theme: DefinedTheme;
+    /** The path of the page on screen, which picks the selected row. */
+    pathname: string;
+    /** Where the package is published. */
+    packages: PackageLinks;
+    /**
+     * The website's address, given when the studio runs away from it. The studio is then this
+     * page, and every other page opens on the website: the pages in a new tab, so the studio stays open.
+     */
+    site?: string;
+    /** What sits at the foot of the rail. */
+    footerIcons?: ReactNode;
+}
+/** The icon rail: the mark, the website's pages, and where the package is published. */
+export declare function StudioRail({ theme, pathname, packages, site, footerIcons }: StudioRailProps): import("react").JSX.Element;
+/**
+ * Publishes where the shell's page sits as `--shell-top|right|bottom|left` (distance from each
+ * viewport edge). A dialog lives in the browser's top layer, which a clip cannot reach, so
+ * studio-shell.css insets it to this box and it centres there.
+ */
+export declare function ShellBounds(): null;
+export {};

package/ui/studio-shell.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The shell the studio sits in: the icon rail on the black base, and the page beside it. The
+ * website frames every page with these; the studio on its own frames its one page the same way.
+ */
+import { Icon } from '@astryxdesign/core/Icon';
+import { SideNav, SideNavHeading, SideNavItem, SideNavSection } from '@astryxdesign/core/SideNav';
+import { Theme } from '@astryxdesign/core/theme';
+import { IconBook2, IconBrandGithub, IconBrandNpm, IconPlayerPlay } from '@tabler/icons-react';
+import { useEffect } from 'react';
+import { SITE_PAGES } from "./studio-nav.js";
+import { IconTheorem } from "./theorem-mark.js";
+import './studio-shell.css';
+/**
+ * JSR brand mark (from jsr.io's icon), filled in the current colour. It spans the
+ * full 24-unit box, as Tabler's brand-npm does with its stroke, so Astryx's icon
+ * sizing sets both at the same visual size.
+ */
+function IconJsr(props) {
+    return (_jsx("svg", { viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": true, ...props, children: _jsx("path", { d: "M3.692 5.538v3.693H0v7.384h7.385v1.847h12.923v-3.693H24V7.385h-7.385V5.538Zm1.846 1.847h1.847v7.384H1.846v-3.692h1.846v1.846h1.846zm3.693 0h5.538V9.23h-3.692v1.846h3.692v5.538H9.231V14.77h3.692v-1.846H9.231Zm7.384 1.846h5.539v3.692h-1.846v-1.846h-1.846v5.538h-1.847z" }) }));
+}
+/**
+ * Astryx link component for off-site destinations: opens in a new tab with no opener.
+ * Astryx hands custom link components `to` alongside `href` (for routers); a plain anchor drops it.
+ */
+function NewTabLink({ to: _to, ...props }) {
+    return _jsx("a", { ...props, target: "_blank", rel: "noopener noreferrer" });
+}
+/** The icon each of the rail's rows carries, by its label. */
+export const PAGE_ICONS = { Studio: IconPlayerPlay, Docs: IconBook2 };
+export const PACKAGE_ICONS = { GitHub: IconBrandGithub, JSR: IconJsr, npm: IconBrandNpm };
+/** A rail row's icon, a size up from the rail's own, so the marks read on a large screen. */
+function railIcon(icon, isSelected = false) {
+    return _jsx(Icon, { icon: icon, size: "md", color: isSelected ? 'inherit' : 'secondary' });
+}
+/** The icon rail: the mark, the website's pages, and where the package is published. */
+export function StudioRail({ theme, pathname, packages, site, footerIcons }) {
+    const at = (href) => {
+        if (site === undefined)
+            return href;
+        return href === '/studio' ? '/studio/' : `${site}${href}`;
+    };
+    return (_jsx(Theme, { theme: theme, mode: "dark", children: _jsxs(SideNav, { collapsible: { isCollapsed: true, hasButton: false }, header: _jsx(SideNavHeading, { heading: "theorem", headingHref: at('/'), icon: railIcon(IconTheorem, true) }), footerIcons: footerIcons, children: [_jsx(SideNavSection, { title: "Site", isHeaderHidden: true, children: SITE_PAGES.map(({ label, href }) => {
+                        const isSelected = pathname === href || pathname.startsWith(`${href}/`);
+                        return (_jsx(SideNavItem, { label: label, href: at(href), size: "lg", icon: railIcon(PAGE_ICONS[label], isSelected), as: site !== undefined && href !== '/studio' ? NewTabLink : undefined, isSelected: isSelected, "data-home-nav-anchor": href }, href));
+                    }) }), _jsx(SideNavSection, { title: "Packages", isHeaderHidden: true, children: packages.map(({ label, href }) => (_jsx(SideNavItem, { label: label, href: href, size: "lg", icon: railIcon(PACKAGE_ICONS[label]), as: NewTabLink, "data-home-nav-anchor": href }, href))) })] }) }));
+}
+const MAIN_ID = 'astryx-app-shell-main';
+const VARS = ['top', 'right', 'bottom', 'left'];
+/**
+ * Publishes where the shell's page sits as `--shell-top|right|bottom|left` (distance from each
+ * viewport edge). A dialog lives in the browser's top layer, which a clip cannot reach, so
+ * studio-shell.css insets it to this box and it centres there.
+ */
+export function ShellBounds() {
+    useEffect(() => {
+        const root = document.documentElement;
+        const main = document.getElementById(MAIN_ID);
+        if (!main)
+            return;
+        const measure = () => {
+            const box = main.getBoundingClientRect();
+            const edges = {
+                top: box.top,
+                right: globalThis.innerWidth - box.right,
+                bottom: globalThis.innerHeight - box.bottom,
+                left: box.left,
+            };
+            for (const edge of VARS)
+                root.style.setProperty(`--shell-${edge}`, `${String(Math.max(0, edges[edge]))}px`);
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(main);
+        globalThis.addEventListener('resize', measure);
+        /* The shell moves between pages without resizing; re-measure as a dialog opens. */
+        document.addEventListener('beforetoggle', measure, true);
+        return () => {
+            observer.disconnect();
+            globalThis.removeEventListener('resize', measure);
+            document.removeEventListener('beforetoggle', measure, true);
+            for (const edge of VARS)
+                root.style.removeProperty(`--shell-${edge}`);
+        };
+    }, []);
+    return null;
+}

package/ui/studio-theme.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The look of the studio and the shell it sits in: Theorem's theme on a black base, with the page
+ * drawn as a rounded panel inset from the viewport edges beside the rail. The website's theme
+ * extends this one, so the studio looks the same on the website and on its own.
+ * `npm --prefix studio run theme:build` compiles it to `built/`, which is what a page imports.
+ */
+export declare const studioTheme: import("@astryxdesign/core/theme").ResolvedDefinedTheme;

package/ui/studio-theme.js

@@ -0,0 +1,94 @@
+import { defineTheme } from '@astryxdesign/core/theme';
+import { tablerIcons } from '@theoremjs/react/ui/icons';
+import { theoremTheme } from '@theoremjs/react/ui/theme';
+/**
+ * The look of the studio and the shell it sits in: Theorem's theme on a black base, with the page
+ * drawn as a rounded panel inset from the viewport edges beside the rail. The website's theme
+ * extends this one, so the studio looks the same on the website and on its own.
+ * `npm --prefix studio run theme:build` compiles it to `built/`, which is what a page imports.
+ */
+export const studioTheme = defineTheme({
+    name: 'theorem-studio',
+    extends: theoremTheme,
+    // Restated so the built module carries the registry; a build keeps only the icons its source imports.
+    icons: tablerIcons,
+    tokens: {
+        // Behind the rail and the page panel, in both modes.
+        '--color-background-body': '#000000',
+        // The type ladder, a step above Astryx's: body is 16px, not 14px. Text and heading types read these.
+        '--font-size-xs': '0.6875rem',
+        '--font-size-sm': '0.875rem',
+        '--font-size-base': '1rem',
+        '--font-size-lg': '1.1875rem',
+        '--font-size-xl': '1.375rem',
+        '--font-size-2xl': '1.625rem',
+        '--font-size-3xl': '2rem',
+        '--font-size-4xl': '2.375rem',
+        '--font-size-5xl': '2.75rem',
+    },
+    components: {
+        // why: Astryx fixes every toast at 400px, so a short message sits in a wide empty box. Let it
+        // size to its text; the viewport lines toasts up on the end edge, so the toast stays there.
+        toast: {
+            base: {
+                width: 'fit-content',
+                minWidth: 'min(240px, 100%)',
+                justifySelf: 'end',
+            },
+        },
+        // AppShell's elevated variant only rounds the panel when a TopNav is
+        // present; with the rail alone, inset top, bottom, and the trailing edge.
+        // The leading edge stays flush to the rail. The matching start inset
+        // is added in studio-shell.css only below the drawer breakpoint.
+        'layout-content': {
+            base: {
+                ':where([role="main"])': {
+                    height: 'calc(100% - 2 * var(--spacing-4))',
+                    marginBlock: 'var(--spacing-4)',
+                    marginInlineEnd: 'var(--spacing-4)',
+                    borderRadius: 'var(--radius-page)',
+                },
+            },
+        },
+        // A clear gap between rail groups; Astryx's own section spacing reads as one list.
+        'side-nav-section': {
+            base: {
+                paddingBlock: 'var(--spacing-3)',
+            },
+        },
+        // Neutral's selected fill (accent-muted) matches the dark page surface, so a selected row
+        // vanishes; the pressed overlay reads on any surface in either mode.
+        'tree-list-item': {
+            'selected:selected': {
+                backgroundColor: 'var(--color-overlay-pressed)',
+            },
+        },
+        // A name longer than its column (a tool's snake_case, which never wraps) ends in an ellipsis
+        // rather than running under the column's edge.
+        'tree-list-item-label': {
+            base: {
+                minWidth: '0',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+            },
+        },
+        // Same fill and corners as the elevated shell's page panel (surface + radius-page, no border),
+        // for pages that sit on the base and draw their own panels.
+        section: {
+            'variant:raised': {
+                backgroundColor: 'var(--color-background-surface)',
+                borderRadius: 'var(--radius-page)',
+                // Content scrolling past the rounded corners would otherwise draw outside them.
+                overflow: 'clip',
+            },
+        },
+        // Inline code in prose reads as part of its sentence: the sentence's own typeface, at its size
+        // and weight. Astryx sets it in the code typeface.
+        code: {
+            base: {
+                fontFamily: 'inherit',
+            },
+        },
+    },
+});