@theoremjs/studio 0.0.0-stage → 0.3.2

package/ui/provider-editor.d.ts

@@ -0,0 +1,15 @@
+import { type StudioIssue, type StudioProvider, type StudioWorkspace } from '../mod.ts';
+/**
+ * The editor for one provider: its adapter, what it connects with, as its adapter takes it, the
+ * key slots its models read, and what its models take. Its id is what code and models name it by,
+ * so only a provider the files do not hold yet takes a new one, through `onRename`, and an adapter
+ * the project made itself stays its code's. `onChange` is left out where the
+ * providers are the studio's own: every row then shows its value and takes no edit.
+ */
+export declare function ProviderEditor({ workspace, provider, issues, onChange, onRename, }: {
+    workspace: StudioWorkspace;
+    provider: StudioProvider;
+    issues: readonly StudioIssue[];
+    onChange?: (next: StudioProvider) => void;
+    onRename?: (id: string) => void;
+}): import("react").JSX.Element;

package/ui/provider-editor.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Section } from '@astryxdesign/core/Section';
+import { StackItem } from '@astryxdesign/core/Stack';
+import { Text } from '@astryxdesign/core/Text';
+import { TextInput } from '@astryxdesign/core/TextInput';
+import { VStack } from '@astryxdesign/core/VStack';
+import { useState } from 'react';
+import { connectionFields, kernelDefinitions, providerUse, takesKey, } from "../mod.js";
+import { ChoiceRow, InspectorRow, InspectorSection, SetInCode, TextRow } from "./inspector.js";
+import { NodeIssues } from "./inspector-context.js";
+import { IssueBanners, SlotRow } from "./profile-editor.js";
+/** A connection setting's name as a row labels it: `baseURL` is Base URL. */
+function settingLabel(name) {
+    const words = name.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/\bUrl\b/g, 'URL');
+    const [first = '', ...rest] = words.split(' ');
+    const lower = rest.map((word) => (word === 'URL' ? word : word.toLowerCase()));
+    return [first.charAt(0).toUpperCase() + first.slice(1), ...lower].join(' ');
+}
+/** How many models run on the provider, and across how many agents. */
+function usedBy(workspace, id) {
+    const { models, agents } = providerUse(workspace, id);
+    if (models === 0)
+        return 'No model runs on it.';
+    const plural = (count, word) => `${String(count)} ${word}${count === 1 ? '' : 's'}`;
+    return `${plural(models, 'model')} in ${plural(agents, 'agent')} ${models === 1 ? 'runs' : 'run'} on it.`;
+}
+/** `provider` with the text setting `name` of `field` set, or left out once it is blank. */
+function withText(provider, field, value) {
+    const { [field]: _was, ...rest } = provider;
+    return value ? { ...rest, [field]: value } : rest;
+}
+function withConnection(provider, name, value) {
+    const { [name]: _was, ...rest } = provider.connection ?? {};
+    return { ...provider, connection: value ? { ...rest, [name]: value } : rest };
+}
+/**
+ * `provider` registered from the kernel definition `definition`, keeping what it connects with
+ * that the definition also takes.
+ */
+function withDefinition(provider, definition) {
+    const takes = new Set(connectionFields(definition)?.map((field) => field.name));
+    const kept = Object.entries(provider.connection ?? {}).filter(([name]) => takes.has(name));
+    return { ...provider, definition, connection: Object.fromEntries(kept) };
+}
+/**
+ * A new provider's id, renamed as it is left or on Enter, so its page stays open while it is typed.
+ * A blank or taken id says why and goes back to the one it has.
+ */
+function ProviderIdRow({ id, taken, onRename, }) {
+    const [typed, setTyped] = useState(id);
+    const name = typed.trim();
+    const problem = !name
+        ? 'A provider needs an id.'
+        : name !== id && taken.includes(name)
+            ? `A provider named '${name}' is already here.`
+            : undefined;
+    const commit = () => {
+        if (problem)
+            setTyped(id);
+        else if (name !== id)
+            onRename(name);
+    };
+    return (_jsx(InspectorRow, { label: "Id", path: "id", isRequired: true, hasIssue: problem !== undefined, hasNote: problem !== undefined, children: _jsx(StackItem, { size: "fill", children: _jsx(TextInput, { label: "Id", isLabelHidden: true, size: "sm", value: typed, status: problem ? { type: 'error', message: problem } : undefined, onChange: setTyped, onEnter: commit, onBlur: commit }) }) }));
+}
+/**
+ * The editor for one provider: its adapter, what it connects with, as its adapter takes it, the
+ * key slots its models read, and what its models take. Its id is what code and models name it by,
+ * so only a provider the files do not hold yet takes a new one, through `onRename`, and an adapter
+ * the project made itself stays its code's. `onChange` is left out where the
+ * providers are the studio's own: every row then shows its value and takes no edit.
+ */
+export function ProviderEditor({ workspace, provider, issues, onChange, onRename, }) {
+    const held = connectionFields(provider.definition);
+    const set = onChange ?? (() => undefined);
+    // A setting its definition does not take still gets a row, so its issue shows and it can be cleared.
+    const extra = Object.keys(provider.connection ?? {})
+        .filter((name) => !held?.some((field) => field.name === name))
+        .map((name) => ({ name, required: false, url: false }));
+    // The studio's own show only what they are set with: a blank row would say more than the studio knows.
+    const fields = held && [...held, ...extra].filter((field) => onChange || provider.connection?.[field.name]);
+    // A definition that signs in with no key reads no slot; one set anyway still shows, so its issue can be cleared.
+    const slots = ['keySlot', 'fallbackKeySlot'].filter((slot) => provider[slot] || (onChange && takesKey(provider.definition)));
+    const rows = (_jsxs(_Fragment, { children: [fields === undefined ? (_jsx(InspectorSection, { title: "Connection", note: "Its definition is the project's own, so what it connects with is the definition's to say.", children: null })) : (fields.length > 0 && (_jsx(InspectorSection, { title: "Connection", children: fields.map((field) => (_jsx(TextRow, { label: settingLabel(field.name), path: `connection.${field.name}`, field: `connection.${field.name}`, isRequired: field.required, value: provider.connection?.[field.name] ?? '', placeholder: field.url ? 'https://' : undefined, onChange: (value) => {
+                        set(withConnection(provider, field.name, value.trim()));
+                    } }, field.name))) }))), slots.length > 0 && (_jsx(InspectorSection, { title: "Keys", note: "The slots its models read their key from, unless a model names its own.", children: slots.map((slot) => (_jsx(SlotRow, { label: slot === 'keySlot' ? 'Key slot' : 'Fallback slot', path: slot, field: slot, value: provider[slot] ?? '', onChange: (next) => {
+                        set(withText(provider, slot, next));
+                    } }, slot))) }))] }));
+    return (_jsx(NodeIssues, { value: issues, children: _jsxs(VStack, { children: [_jsx(IssueBanners, { issues: issues }), _jsxs(InspectorSection, { title: "Provider", note: usedBy(workspace, provider.id), children: [onRename ? (_jsx(ProviderIdRow, { id: provider.id, taken: workspace.providers.map((each) => each.id), onRename: onRename })) : (_jsx(InspectorRow, { label: "Id", path: "id", children: _jsx(Text, { children: provider.id }) })), onChange && held ? (_jsx(ChoiceRow, { label: "Definition", path: "definition", field: "definition", isRequired: true, value: provider.definition, options: kernelDefinitions(), onChange: (next) => {
+                                if (next && next !== provider.definition)
+                                    onChange(withDefinition(provider, next));
+                            } })) : (_jsx(InspectorRow, { label: "Definition", path: "definition", children: _jsx(Text, { children: provider.definition }) }))] }), onChange ? (rows) : (_jsxs(_Fragment, { children: [_jsx(Section, { variant: "transparent", padding: 3, children: _jsx(Text, { type: "supporting", color: "secondary", children: "The studio's own provider: the studio decides what it connects with. A project's providers are changed here." }) }), _jsx(SetInCode, { children: rows })] }))] }) }));
+}

package/ui/read-map.css

@@ -0,0 +1,48 @@
+/* The loader's map of a project being read. It fills the loader's panel. */
+.read-map {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+}
+
+.read-map-lines {
+  position: absolute;
+  inset: 0 auto auto 0;
+  pointer-events: none;
+}
+
+/* The line draws in from the node it leaves. */
+.read-map-line {
+  stroke-dasharray: 1;
+  stroke-dashoffset: 1;
+  animation: read-map-line-in var(--duration-medium, 240ms) var(--ease-standard, ease-out) forwards;
+}
+
+.read-map-dot {
+  fill: var(--color-text-secondary);
+  animation: read-map-in var(--duration-fast, 120ms) var(--ease-standard, ease-out) both;
+}
+
+.read-map-node {
+  animation: read-map-in var(--duration-medium, 240ms) var(--ease-standard, ease-out) both;
+}
+
+.read-map-foot {
+  position: absolute;
+  inset: auto var(--spacing-4) var(--spacing-4) var(--spacing-4);
+  display: flex;
+  gap: 16px;
+  justify-content: space-between;
+}
+
+@keyframes read-map-line-in {
+  to {
+    stroke-dashoffset: 0;
+  }
+}
+
+@keyframes read-map-in {
+  from {
+    opacity: 0;
+  }
+}

package/ui/read-map.d.ts

@@ -0,0 +1,7 @@
+import type { Reading } from './lib/read-progress.ts';
+export interface ReadMapProps {
+    reading: Reading;
+    /** Called once every step is drawn and the project has arrived. */
+    onDrawn: () => void;
+}
+export declare function ReadMap({ reading, onDrawn }: ReadMapProps): import("react").JSX.Element;

package/ui/read-map.js

@@ -0,0 +1,163 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from '@astryxdesign/core/Text';
+import { IconFileCode, IconFileSmile, IconFolder } from '@tabler/icons-react';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { mapCurve } from "../map-line.js";
+import { readMap } from "./lib/read-map.js";
+import { profileTypeIcon, toolTypeIcon } from "./lib/type-icons.js";
+import { MapToken, useTokenWidths } from "./map-token.js";
+import './read-map.css';
+/** The slowest the map draws: one step in this long. */
+const STEP_MS = 70;
+/** While steps still arrive, the map stays about this far behind them. */
+const LAG_MS = 500;
+/** Once the project has arrived, the rest is drawn within this long. */
+const CATCH_UP_MS = 900;
+/** The map shows for at least this long, so a quick read can still be seen. */
+const SHOWN_MS = 2000;
+/** The panel's own padding, step 4. */
+const PAD = 16;
+const ROW = 30;
+/** Room kept for the last column's tokens and for the line of words under the map. */
+const LAST_COL = 190;
+const FOOT = 44;
+const GAP = 8;
+const DOTS = 8;
+const LABEL = 30;
+const NODE_ICON = {
+    entry: IconFileCode,
+    folder: IconFolder,
+    profile: IconFileSmile,
+    tool: undefined,
+    more: undefined,
+};
+/** An agent or a tool has its type's icon, the one the tree gives it. */
+function nodeIcon({ kind, type }) {
+    if (kind === 'profile')
+        return profileTypeIcon(type) ?? NODE_ICON.profile;
+    if (kind === 'tool')
+        return toolTypeIcon(type ?? '');
+    return NODE_ICON[kind];
+}
+function isFile(step) {
+    return 'file' in step && !('found' in step);
+}
+/** A long name keeps its end, which is what tells two paths apart. */
+function short(label) {
+    return label.length > LABEL ? `…${label.slice(1 - LABEL)}` : label;
+}
+/** How far the map has drawn: the steps drawn, of the steps it is laid out from. */
+function useDrawn(reading, onDrawn) {
+    const [drawn, setDrawn] = useState({ steps: 0, known: 0 });
+    const told = useRef(onDrawn);
+    told.current = onDrawn;
+    useEffect(() => {
+        let frame = 0;
+        const start = performance.now();
+        let at = start;
+        let cursor = 0;
+        let pace;
+        const tick = (now) => {
+            const known = reading.steps().length;
+            const left = known - cursor;
+            if (reading.done())
+                pace ??= Math.max(1 / STEP_MS, left / Math.max(CATCH_UP_MS, SHOWN_MS - (now - start)));
+            const rate = pace ?? Math.max(1 / STEP_MS, left / LAG_MS);
+            cursor = Math.min(known, cursor + (now - at) * rate);
+            at = now;
+            const steps = Math.floor(cursor);
+            setDrawn((last) => (last.steps === steps && last.known === known ? last : { steps, known }));
+            if (reading.done() && cursor >= known && now - start >= SHOWN_MS) {
+                told.current();
+                return;
+            }
+            frame = requestAnimationFrame(tick);
+        };
+        frame = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(frame);
+    }, [reading]);
+    return drawn;
+}
+function useSize() {
+    const ref = useRef(null);
+    const [size, setSize] = useState();
+    useLayoutEffect(() => {
+        const root = ref.current;
+        if (!root)
+            return;
+        const measure = () => setSize({ width: root.clientWidth, height: root.clientHeight });
+        measure();
+        const watch = new ResizeObserver(measure);
+        watch.observe(root);
+        return () => watch.disconnect();
+    }, []);
+    return { ref, size };
+}
+/** What the line of words under the map says of the step being drawn. */
+function saying(steps, drawn) {
+    const last = steps[Math.max(0, drawn - 1)];
+    if (!last)
+        return 'Reading your project';
+    if ('again' in last)
+        return 'Your files changed. Loading the project again.';
+    if (isFile(last))
+        return `Reading ${last.file}`;
+    return drawn < steps.length ? 'Finding agents and tools' : 'Opening';
+}
+function counted(count, one) {
+    return count ? `${String(count)} ${one}${count === 1 ? '' : 's'}` : undefined;
+}
+/** What has been drawn so far, counted. */
+function tally(steps, drawn) {
+    const seen = steps.slice(0, drawn);
+    const found = (kind) => seen.filter((step) => 'found' in step && step.found === kind).length;
+    return [
+        counted(seen.filter(isFile).length, 'file'),
+        counted(found('profile'), 'agent'),
+        counted(found('tool'), 'tool'),
+    ]
+        .filter((part) => part !== undefined)
+        .join(' · ');
+}
+/** The line from a node's right edge to the next node's left, and the dots along it. */
+function lineTo(from, fromWidth, to, dots) {
+    const curve = mapCurve({ x: from.x + fromWidth + GAP, y: from.y }, { x: to.x - GAP, y: to.y });
+    return {
+        d: curve.d,
+        dots: Array.from({ length: dots }, (_, index) => curve.at((index + 1) / (dots + 1))),
+    };
+}
+export function ReadMap({ reading, onDrawn }) {
+    const drawn = useDrawn(reading, onDrawn);
+    const { ref, size } = useSize();
+    const steps = reading.steps();
+    const rows = size ? Math.floor((size.height - PAD * 2 - FOOT) / ROW) : 0;
+    // Laid out from every step said so far, not only the ones drawn: drawing a node moves nothing.
+    // A folder first said later does move the rows, and the tokens and lines move together.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `steps` is one list that grows; its length is what changes.
+    const map = useMemo(() => readMap(steps.slice(0, drawn.known), rows), [drawn.known, rows]);
+    const placed = useMemo(() => {
+        if (!size)
+            return [];
+        const stride = map.cols > 1 ? (size.width - PAD * 2 - LAST_COL) / (map.cols - 1) : 0;
+        return map.nodes
+            .filter((node) => node.first < drawn.steps)
+            .map((node) => ({
+            node,
+            x: PAD + node.col * Math.max(stride, 0),
+            y: size.height / 2 + (node.row - (map.rows - 1) / 2) * ROW,
+        }));
+    }, [map, size, drawn.steps]);
+    const widths = useTokenWidths(ref, placed);
+    const byId = new Map(placed.map((each) => [each.node.id, each]));
+    return (_jsxs("div", { ref: ref, className: "read-map", "aria-hidden": "true", children: [_jsx("svg", { className: "read-map-lines", "aria-hidden": "true", width: size?.width ?? 0, height: size?.height ?? 0, children: placed.map((to) => {
+                    const from = to.node.parent === undefined ? undefined : byId.get(to.node.parent);
+                    const width = from && widths[from.node.id];
+                    if (!from || width === undefined)
+                        return null;
+                    const read = to.node.own.filter((step) => step < drawn.steps).length;
+                    const dots = Math.ceil((Math.min(DOTS, to.node.own.length) * read) / Math.max(1, to.node.own.length));
+                    const line = lineTo(from, width, to, Math.min(DOTS, to.node.own.length));
+                    return (_jsxs("g", { children: [_jsx("path", { className: "map-line read-map-line", d: line.d, pathLength: 1 }), line.dots.slice(0, dots).map(({ x, y }, index) => (_jsx("circle", { className: "read-map-dot", cx: x, cy: y, r: 2.5 }, index)))] }, to.node.id));
+                }) }), placed.map(({ node, x, y }) => (_jsx(MapToken, { className: "read-map-node", id: node.id, label: short(node.label), icon: nodeIcon(node), x: x, y: y }, node.id))), _jsxs("div", { className: "read-map-foot", children: [_jsx(Text, { type: "supporting", color: "secondary", maxLines: 1, children: saying(steps, drawn.steps) }), _jsx(Text, { type: "supporting", color: "secondary", maxLines: 1, children: tally(steps, drawn.steps) })] })] }));
+}

package/ui/refusal-detail.d.ts

@@ -0,0 +1,4 @@
+import type { SaveRefusal } from '../server/save-wire.ts';
+export declare function RefusalDetail({ refusal }: {
+    refusal: SaveRefusal;
+}): import("react").JSX.Element | null;

package/ui/refusal-detail.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Why the studio could not run or save the builder's edits, past the headline: the agents and
+ * tools that did not load as edited, or what the project said when it stopped.
+ */
+import { ScrollableArea } from '@astryxdesign/core/ScrollableArea';
+import { Text } from '@astryxdesign/core/Text';
+import { VStack } from '@astryxdesign/core/VStack';
+import { refusalLines } from "./lib/refusal-lines.js";
+/** More lines than this scroll, so a long report does not push the way out off the pane. */
+const LINES_SHOWN = 12;
+const SCROLL_HEIGHT = 240;
+export function RefusalDetail({ refusal }) {
+    const lines = refusalLines(refusal);
+    if (lines.length === 0)
+        return null;
+    const said = (_jsx(VStack, { gap: 1, children: lines.map((line, index) => (_jsx(Text, { type: "supporting", color: "secondary", wordBreak: "break-word", children: line }, index))) }));
+    if (lines.length <= LINES_SHOWN)
+        return said;
+    return (_jsx(ScrollableArea, { label: "Details", height: SCROLL_HEIGHT, children: said }));
+}

package/ui/shared-change.d.ts

@@ -0,0 +1,9 @@
+import type { StudioStore } from './lib/studio-store.ts';
+/**
+ * The stop before a change to a value the project's files write once, or a change to a tool
+ * other profiles allow: who else it changes and what other code reads it, and Cancel or Change for all. Closing the dialog is
+ * Cancel, and no profile has the change.
+ */
+export declare function SharedChange({ store }: {
+    store: StudioStore;
+}): import("react").JSX.Element;

package/ui/shared-change.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '@astryxdesign/core/Button';
+import { CheckboxInput } from '@astryxdesign/core/CheckboxInput';
+import { Dialog, DialogHeader } from '@astryxdesign/core/Dialog';
+import { HStack } from '@astryxdesign/core/HStack';
+import { Layout, LayoutContent, LayoutFooter } from '@astryxdesign/core/Layout';
+import { useState, useSyncExternalStore } from 'react';
+import { reachesOthers, sharedAsk } from "../mod.js";
+import { askLine } from "./file-place.js";
+const DIALOG_WIDTH = 520;
+/**
+ * The stop before a change to a value the project's files write once, or a change to a tool
+ * other profiles allow: who else it changes and what other code reads it, and Cancel or Change for all. Closing the dialog is
+ * Cancel, and no profile has the change.
+ */
+export function SharedChange({ store }) {
+    const reach = useSyncExternalStore(store.subscribe, store.getPending, store.getPending);
+    const [quiet, setQuiet] = useState(false);
+    const ask = reach && sharedAsk(reach, store.getWorkspace());
+    return (_jsx(Dialog, { isOpen: reach !== undefined, purpose: "form", width: DIALOG_WIDTH, onOpenChange: (isOpen) => {
+            if (!isOpen)
+                store.cancelShared();
+        }, children: ask && (_jsx(Layout, { header: _jsx(DialogHeader, { title: ask.title, subtitle: askLine(ask) }), content: _jsx(LayoutContent, { children: _jsx(CheckboxInput, { label: "Don't ask again this session", value: quiet, onChange: setQuiet }) }), footer: _jsx(LayoutFooter, { children: _jsxs(HStack, { gap: 2, justify: "end", children: [_jsx(Button, { label: "Cancel", variant: "ghost", onClick: () => {
+                                store.cancelShared();
+                            } }), _jsx(Button, { label: reachesOthers(reach) ? 'Change for all' : 'Change', variant: "primary", onClick: () => {
+                                store.confirmShared(quiet);
+                            } })] }) }) })) }));
+}

package/ui/shell-motion.css

@@ -0,0 +1,121 @@
+/* One shell. While the mark draws it is the whole viewport; then that same panel moves to the shape
+   of the page. The scrollport size never changes — only the clip does. */
+@media (width >= 768px) {
+  html[data-boot-pending] .astryx-app-shell,
+  html[data-shell-move] .astryx-app-shell {
+    position: relative;
+    height: 100dvh;
+  }
+
+  html[data-boot-pending] .astryx-app-shell .astryx-app-shell-sidenav,
+  html[data-shell-move] .astryx-app-shell .astryx-app-shell-sidenav {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: 0;
+    z-index: 0;
+    width: var(--spacing-12);
+    transition: none;
+  }
+
+  html[data-boot-pending] .astryx-app-shell [role="main"],
+  html[data-shell-move] .astryx-app-shell [role="main"] {
+    position: relative;
+    z-index: 1;
+    width: 100%;
+    height: 100%;
+    max-width: none;
+    margin: 0;
+    border-radius: 0;
+  }
+
+  /* While the mark draws on the boot screen, the panel is the full viewport. No rail, no inset. */
+  html[data-boot-pending] .astryx-app-shell [role="main"] {
+    clip-path: none;
+    background: var(--color-background-surface);
+    transition: none;
+  }
+
+  /* A moving shell is one full-bleed box whose clip is the shape. open is the viewport, regular is
+	   the panel beside the rail, frame is the same panel cut to the width of the page's own surface. */
+  html[data-shell-move] .astryx-app-shell [role="main"] {
+    background: var(--color-background-surface);
+    transition: clip-path 640ms cubic-bezier(0.45, 0.02, 0.15, 1);
+  }
+
+  html[data-shell-clip="open"] .astryx-app-shell [role="main"] {
+    clip-path: inset(0 round 0);
+  }
+
+  html[data-shell-clip="regular"] .astryx-app-shell [role="main"] {
+    clip-path: inset(
+      var(--spacing-4) var(--spacing-4) var(--spacing-4) var(--spacing-12) round var(--radius-page)
+    );
+  }
+
+  html[data-shell-clip="frame"] .astryx-app-shell [role="main"] {
+    clip-path: inset(
+      var(--spacing-4) calc(100% - var(--spacing-12) - var(--shell-frame-width, 0px))
+        var(--spacing-4) var(--spacing-12) round var(--radius-page)
+    );
+  }
+
+  /* The page stays out while the shell moves. It comes in once the shell has settled. */
+  html[data-shell-move] #astryx-app-shell-main > :not([data-boot]):not(.nav-mark) {
+    visibility: hidden;
+  }
+}
+
+html {
+  --shell-hold-ms: 140ms; /* keep in step with HOLD_MS in shell-motion.ts */
+  --shell-fade: shell-content-in 280ms cubic-bezier(0.45, 0.02, 0.15, 1);
+}
+
+@keyframes shell-content-in {
+  from {
+    opacity: 0;
+  }
+}
+
+/* A page that is about to leave fades out first, then the shell moves. */
+html[data-shell-hold]
+  #astryx-app-shell-main
+  > :not([data-boot]):not(.nav-mark):not(:has([data-shell-frame])),
+html[data-shell-hold] .shell-fade {
+  opacity: 0;
+  visibility: hidden;
+  transition:
+    opacity var(--shell-hold-ms) ease,
+    visibility 0s linear var(--shell-hold-ms);
+}
+
+html[data-shell-in] #astryx-app-shell-main > :not([data-boot]) {
+  animation: var(--shell-fade);
+}
+
+/* A framed page's surface is already in place, because the panel contracted to it. It holds still.
+   What is on it, and the page's other parts, name themselves with .shell-fade and fade in. */
+html[data-shell-in] #astryx-app-shell-main > :has([data-shell-frame]) {
+  animation: none;
+}
+
+html[data-shell-in] .shell-fade {
+  animation: var(--shell-fade);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html[data-shell-hold] #astryx-app-shell-main > :not([data-boot]),
+  html[data-shell-hold] .shell-fade {
+    transition: none;
+  }
+
+  html[data-shell-in] #astryx-app-shell-main > :not([data-boot]),
+  html[data-shell-in] .shell-fade {
+    animation: none;
+  }
+}
+
+/* The contracted shape is a clip on a viewport-tall box. The frame that drops
+   the clip must already be the resting panel, not that tall box easing shut. */
+html[data-shell-in] #astryx-app-shell-main:not(#\#):not(#\#):not(#\#):not(#\#) {
+  transition: none;
+}

package/ui/shell-motion.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The shell is one surface. It starts as the whole viewport, where the mark draws, and moves to
+ * the shape of the page it opens. The website and the studio on its own both move it with this.
+ */
+export declare function bootHasPlayed(): boolean;
+/** Fired when the mark gives way, before the shell moves, so the cover attribute can drop. */
+export declare const SHELL_REVEAL = "theorem-shell-reveal";
+/** Fired when the shell has settled and scroll may own it again. */
+export declare const SHELL_INTRO_DONE = "theorem-shell-intro-done";
+/**
+ * The shapes the shell rests in:
+ * - open: the whole viewport.
+ * - regular: the panel beside the rail.
+ * - frame: the panel's start edge, as wide as the page's own surface. The studio's editor.
+ */
+export type ShellShape = {
+    kind: 'open';
+} | {
+    kind: 'regular';
+} | {
+    kind: 'frame';
+    width: number;
+};
+export type ShellKind = ShellShape['kind'];
+export declare const OPEN_SHAPE: ShellShape;
+export declare const REGULAR_SHAPE: ShellShape;
+/** How long content takes to fade out. Keep in step with `--shell-hold-ms` in shell-motion.css. */
+export declare const HOLD_MS = 140;
+/**
+ * The shape of a page whose shell is a surface inside the page area, measured from the page on
+ * screen. That surface carries `data-shell-frame`; a page without one rests in the regular shape.
+ */
+export declare function frameShape(): ShellShape;
+export declare function captureShape(shape: ShellShape): void;
+export declare function hasCapturedShape(): boolean;
+export declare function peekShape(): ShellShape;
+/** The shape the shell is leaving, and the claim on it: the next route change starts afresh. */
+export declare function takeShape(): ShellShape;
+export declare function prefersReducedMotion(): boolean;
+export declare function sleep(ms: number): Promise<void>;
+/** The host names when something of its own holds the shell still. */
+export declare function pinShellWhile(check: () => boolean): void;
+/** Whether the shell can move. A narrow screen, reduced motion, and a host's pin cannot. */
+export declare function shellCanMove(): boolean;
+/** The mark is still up, or the shell is on its way: scroll must not move the shell yet. */
+export declare function shellIntroOwnsPull(): boolean;
+/** The page's content fades out and stays out until the shell settles. */
+export declare function holdShell(): void;
+/**
+ * Put the shell into move mode at the shape it is in. A route that mounts under it then finds the
+ * shell already drawn as a clip and cannot snap it to its own shape.
+ */
+export declare function enterShell(from: ShellShape): void;
+/**
+ * Move the shell from one shape to another, content hidden. If it is already moving, it carries on
+ * from the shape it is in. Resolves true when it arrives, false when a newer move overtook it. It
+ * stays in its last shape until `settleShell`, so a page that is still loading can wait on it.
+ */
+export declare function moveShell(from: ShellShape, to: ShellShape): Promise<boolean>;
+/** The shell rests. The page's content comes in at the size it will keep. */
+export declare function settleShell(to: ShellShape): void;
+/**
+ * The mark has finished but the page is still loading. The shell pulls in to the regular panel and
+ * waits there, page hidden, for what the loader shows on it. `revealShell` then takes it to rest.
+ * A shell that cannot move stays full-bleed.
+ */
+export declare function pullShellIn(): Promise<boolean>;
+/**
+ * The loader has finished. The page stays hidden while the shell moves to the shape of the page it
+ * opens, then comes in. It moves from the full-bleed shell, or from the regular panel when
+ * `pullShellIn` took it there. A page that rests open stays open.
+ */
+export declare function revealShell(to: ShellShape): void;