@intentic/extension-ui 1.247.0 → 1.249.0

package/dist/types/ui/src/index.d.ts

@@ -2,72 +2,73 @@ export { clipboardOf } from "./lib/clipboard.js";
 export { appLink, browserOwnsClick } from "./lib/link.js";
 export { openForwardedPort } from "./lib/portPreview.js";
 export { ui } from "./lib/ui.js";
-export { default as AgentRunButton } from "./components/AgentRunButton.vue";
+export { default as AgentRunButton } from "./components/sandbox/AgentRunButton.vue";
 export { type AgentRunChoice, type AgentRunPicker, type ModelPicking, useAgentRunPick } from "./composables/useAgentRunPick.js";
-export { default as AnchoredOverlay } from "./components/AnchoredOverlay.vue";
-export { default as Avatar } from "./components/Avatar.vue";
-export { default as BarChart } from "./components/BarChart.vue";
-export { default as BottomSheet } from "./components/BottomSheet.vue";
-export { default as BrandMark } from "./components/BrandMark.vue";
-export { default as Button } from "./components/Button.vue";
+export { default as AnchoredOverlay } from "./components/overlays/AnchoredOverlay.vue";
+export { default as Avatar } from "./components/brand/Avatar.vue";
+export { default as BarChart } from "./components/charts/BarChart.vue";
+export { default as BottomSheet } from "./components/layout/BottomSheet.vue";
+export { default as BrandMark } from "./components/brand/BrandMark.vue";
+export { default as Button } from "./components/primitives/Button.vue";
 export { vAction } from "./lib/pressAction.js";
-export { default as Card } from "./components/Card.vue";
-export { default as ChangeStatusMark } from "./components/ChangeStatusMark.vue";
-export { type ChangeStatus } from "./components/changeStatus.js";
-export { default as DiffStat } from "./components/DiffStat.vue";
-export { default as Code } from "./components/Code.vue";
-export { default as CodeField } from "./components/CodeField.vue";
-export { default as ConfirmDialog } from "./components/ConfirmDialog.vue";
-export { default as ContextMenu } from "./components/ContextMenu.vue";
-export { default as CopyButton } from "./components/CopyButton.vue";
-export { type TallyItem, default as StatusTally } from "./components/StatusTally.vue";
-export { default as DagEditor } from "./components/DagEditor.vue";
-export { default as DagGraph } from "./components/DagGraph.vue";
-export { default as DisclosureRow } from "./components/DisclosureRow.vue";
-export { type DagEdge, type DagNode } from "./components/dagLayout.js";
-export { default as FilterBar } from "./components/FilterBar.vue";
-export { default as Icon } from "./components/Icon.vue";
-export { default as ImageView } from "./components/ImageView.vue";
-export { isRenderableImage } from "./components/imageView.js";
-export { default as InfoDialog } from "./components/InfoDialog.vue";
-export { default as InfoHint } from "./components/InfoHint.vue";
-export { default as InfoTable } from "./components/InfoTable.vue";
-export { default as Markdown } from "./components/Markdown.vue";
-export { default as MarkdownFigure } from "./components/MarkdownFigure.vue";
-export { default as Modal } from "./components/Modal.vue";
-export { default as NavRail } from "./components/NavRail.vue";
-export { type NavGroup } from "./components/navRail.js";
-export { default as NoteEditor } from "./components/NoteEditor.vue";
+export { default as Card } from "./components/layout/Card.vue";
+export { default as ChangeStatusMark } from "./components/feedback/ChangeStatusMark.vue";
+export { type ChangeStatus } from "./components/feedback/changeStatus.js";
+export { default as DiffStat } from "./components/charts/DiffStat.vue";
+export { default as Code } from "./components/primitives/Code.vue";
+export { default as CodeField } from "./components/forms/CodeField.vue";
+export { default as ConfirmDialog } from "./components/overlays/ConfirmDialog.vue";
+export { default as ContextMenu } from "./components/overlays/ContextMenu.vue";
+export { default as CopyButton } from "./components/primitives/CopyButton.vue";
+export { type TallyItem, default as StatusTally } from "./components/charts/StatusTally.vue";
+export { default as DagEditor } from "./components/charts/DagEditor.vue";
+export { default as DagGraph } from "./components/charts/DagGraph.vue";
+export { default as DisclosureRow } from "./components/rows/DisclosureRow.vue";
+export { type DagEdge, type DagNode } from "./components/charts/dagLayout.js";
+export { default as FilterBar } from "./components/forms/FilterBar.vue";
+export { default as Icon } from "./components/primitives/Icon.vue";
+export { default as ImageView } from "./components/primitives/ImageView.vue";
+export { isRenderableImage } from "./components/primitives/imageView.js";
+export { default as InfoDialog } from "./components/overlays/InfoDialog.vue";
+export { default as InfoHint } from "./components/feedback/InfoHint.vue";
+export { default as InfoTable } from "./components/feedback/InfoTable.vue";
+export { default as Markdown } from "./components/markdown/Markdown.vue";
+export { default as MarkdownDocument } from "./components/markdown/MarkdownDocument.vue";
+export { default as MarkdownFigure } from "./components/charts/MarkdownFigure.vue";
+export { default as Modal } from "./components/overlays/Modal.vue";
+export { default as NavRail } from "./components/layout/NavRail.vue";
+export { type NavGroup } from "./components/layout/navRail.js";
+export { default as NoteEditor } from "./components/forms/NoteEditor.vue";
 export { type NoteDraft, type NoteDraftOptions, useNoteDraft } from "./composables/useNoteDraft.js";
 export { useKeyedDraft } from "./composables/useKeyedDraft.js";
-export { default as Notice } from "./components/Notice.vue";
-export { default as NoticeStack } from "./components/NoticeStack.vue";
-export { type NoticeAction, type NoticeModel, type NoticeTone } from "./components/notice.js";
-export { default as Page } from "./components/Page.vue";
-export { default as PageAction } from "./components/PageAction.vue";
-export { default as PageHeader } from "./components/PageHeader.vue";
-export { default as PersonaFace } from "./components/PersonaFace.vue";
-export { type PersonaLike } from "./components/personaFace.js";
-export { default as ScrollFrame } from "./components/ScrollFrame.vue";
-export { default as Picker } from "./components/Picker.vue";
-export { type PickerGroup, type PickerOption, type PickerOptions } from "./components/picker.js";
-export { default as ProgressRing } from "./components/ProgressRing.vue";
-export { default as ProseField } from "./components/ProseField.vue";
-export { default as RepoRail } from "./components/RepoRail.vue";
-export { type RepoRailAll, type RepoRailGroup, type RepoRailRow } from "./components/repoRail.js";
-export { default as ResizeSeam } from "./components/ResizeSeam.vue";
-export { default as ResponsiveOverlay } from "./components/ResponsiveOverlay.vue";
-export { default as Row } from "./components/Row.vue";
-export { default as RowGroup } from "./components/RowGroup.vue";
-export { default as SearchBar } from "./components/SearchBar.vue";
-export { default as SegmentedControl } from "./components/SegmentedControl.vue";
-export { seriesColor } from "./components/seriesAccent.js";
-export { default as SkeletonRows } from "./components/SkeletonRows.vue";
-export { default as SplitView } from "./components/SplitView.vue";
-export { useCompact } from "./components/splitView.js";
-export { default as StatStrip } from "./components/StatStrip.vue";
-export { default as StatusBadge, type StatusVariant } from "./components/StatusBadge.vue";
-export { default as StepSection } from "./components/StepSection.vue";
+export { default as Notice } from "./components/feedback/Notice.vue";
+export { default as NoticeStack } from "./components/feedback/NoticeStack.vue";
+export { type NoticeAction, type NoticeModel, type NoticeTone } from "./components/feedback/notice.js";
+export { default as Page } from "./components/layout/Page.vue";
+export { default as PageAction } from "./components/layout/PageAction.vue";
+export { default as PageHeader } from "./components/layout/PageHeader.vue";
+export { default as PersonaFace } from "./components/brand/PersonaFace.vue";
+export { type PersonaLike } from "./components/brand/personaFace.js";
+export { default as ScrollFrame } from "./components/layout/ScrollFrame.vue";
+export { default as Picker } from "./components/forms/Picker.vue";
+export { type PickerGroup, type PickerOption, type PickerOptions } from "./components/forms/picker.js";
+export { default as ProgressRing } from "./components/charts/ProgressRing.vue";
+export { default as ProseField } from "./components/forms/ProseField.vue";
+export { default as RepoRail } from "./components/layout/RepoRail.vue";
+export { type RepoRailAll, type RepoRailGroup, type RepoRailRow } from "./components/layout/repoRail.js";
+export { default as ResizeSeam } from "./components/layout/ResizeSeam.vue";
+export { default as ResponsiveOverlay } from "./components/overlays/ResponsiveOverlay.vue";
+export { default as Row } from "./components/rows/Row.vue";
+export { default as RowGroup } from "./components/rows/RowGroup.vue";
+export { default as SearchBar } from "./components/forms/SearchBar.vue";
+export { default as SegmentedControl } from "./components/forms/SegmentedControl.vue";
+export { seriesColor } from "./components/charts/seriesAccent.js";
+export { default as SkeletonRows } from "./components/feedback/SkeletonRows.vue";
+export { default as SplitView } from "./components/layout/SplitView.vue";
+export { useCompact } from "./components/layout/splitView.js";
+export { default as StatStrip } from "./components/charts/StatStrip.vue";
+export { default as StatusBadge, type StatusVariant } from "./components/feedback/StatusBadge.vue";
+export { default as StepSection } from "./components/layout/StepSection.vue";
 export { sinceOf, TIME_WINDOWS, type TimeWindow, timeWindowWords } from "./lib/timeWindow.js";
 export { type IconName } from "./icons/iconSets.js";
 export { useDevice } from "./composables/useDevice.js";

package/dist/types/ui/src/lib/format.d.ts

@@ -0,0 +1,15 @@
+export declare const formatBytes: (bytes: number | undefined) => string;
+export declare const formatTokens: (tokens: number) => string;
+export declare const initialsOf: (name: string) => string | undefined;
+export declare const formatDate: (at: number) => string;
+export declare const formatDayMonth: (at: number) => string;
+export declare const formatDateTime: (at: number) => string;
+export declare const formatTimestamp: (at: number) => string;
+export declare const formatTime: (at: number) => string;
+export declare const formatClock: (at: number) => string;
+export declare const formatWeekdayTime: (at: number) => string;
+export declare const timeAgo: (at: number, { now, days }?: {
+    now?: number;
+    days?: boolean;
+}) => string;
+export declare const freshness: (at: number) => string;

package/dist/types/ui/src/markdown/edits.d.ts

@@ -0,0 +1,15 @@
+export interface TextEdit {
+    readonly text: string;
+    readonly start: number;
+    readonly end: number;
+}
+export declare const toggleWrap: (text: string, start: number, end: number, marker: string) => TextEdit;
+export declare const insertLink: (text: string, start: number, end: number) => TextEdit;
+export declare const indentLines: (text: string, start: number, end: number) => TextEdit;
+export declare const outdentLines: (text: string, start: number, end: number) => TextEdit;
+export declare const onListLine: (text: string, offset: number) => boolean;
+export interface ListEnter {
+    readonly edit: TextEdit;
+    readonly ended: boolean;
+}
+export declare const continueList: (text: string, offset: number) => ListEnter | undefined;

package/dist/types/ui/src/markdown/history.d.ts

@@ -0,0 +1,12 @@
+export type EditKind = "typing" | "deleting" | "structural";
+export interface DocumentState {
+    readonly text: string;
+    readonly caret: number;
+}
+export interface MarkdownHistory {
+    readonly reset: (state: DocumentState) => void;
+    readonly record: (state: DocumentState, kind: EditKind, at: number) => void;
+    readonly undo: () => DocumentState | undefined;
+    readonly redo: () => DocumentState | undefined;
+}
+export declare const createMarkdownHistory: () => MarkdownHistory;

package/dist/types/ui/src/markdown/index.d.ts

@@ -1,4 +1,7 @@
 export { blockAtOffset, type MarkdownBlock, type MarkdownBlocks, offsetOfLine, splitMarkdownBlocks } from "./blocks.js";
 export { type CodeBlock, codeBlockHtml, copyCodeFromEvent, escapeHtml } from "./code.js";
+export { continueList, indentLines, insertLink, type ListEnter, onListLine, outdentLines, type TextEdit, toggleWrap } from "./edits.js";
+export { createMarkdownHistory, type DocumentState, type EditKind, type MarkdownHistory } from "./history.js";
+export { blockBody, buildBlockElement, caretAtOffset, offsetOfCaret } from "./sourceDom.js";
 export { type BarsFigure, type BarsFigureItem, type DagFigure, type DagFigureEdge, type DagFigureNode, type Figure, FIGURE_ACCENTS, type FigureAccent, FIGURE_LANGS, JSON_FIGURE_LANGS, type MarkdownSegment, MERMAID_LANG, type MermaidFigure, parseFigure, splitFigureSegments, type StatsFigure, type StatsFigureItem, } from "./figures.js";
 export { createStreamingMarkdown, lexBlocks, lexInline, type MarkdownDecorator, type MarkdownPart, markdownParseCount, type MarkdownToken, renderMarkdown, renderMarkdownParts, type RenderedMarkdown, settledEnd, type StreamingMarkdown, } from "./render.js";

package/dist/types/ui/src/markdown/sourceDom.d.ts

@@ -0,0 +1,7 @@
+export declare const blockBody: (element: Element) => string;
+export declare const buildBlockElement: (source: string) => HTMLElement;
+export declare const offsetOfCaret: (element: HTMLElement, node: Node, offset: number) => number;
+export declare const caretAtOffset: (element: HTMLElement, offset: number) => {
+    readonly node: Node;
+    readonly offset: number;
+} | undefined;

package/names.mjs

@@ -43,6 +43,7 @@ export const extensionUiNames = [
     "InfoTable",
     "isRenderableImage",
     "Markdown",
+    "MarkdownDocument",
     "MarkdownFigure",
     "Modal",
     "NavRail",

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@intentic/extension-ui",
-  "version": "1.247.0",
+  "version": "1.249.0",
   "description": "The UI kit intentic extensions render with, host-provided at runtime (the app's own components via the import map), so extension UI is always native to the shell",
   "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/intentic/intentic.git",
-    "directory": "_editor/extension-ui"
+    "directory": "_shared/extension-ui"
   },
   "files": [
     "dist",

package/src/format.ts

@@ -1,15 +1,7 @@
-/* The kit's formatters, reachable WITHOUT the component barrel.
- *
- * `index.ts` pulls every .vue component in the kit, which is the right trade for an extension's own views but
- * the wrong one for its pure logic: a day-divider label is plain arithmetic on a number, and an extension's
- * node-environment tests run without a Vue plugin to parse SFCs with. Importing a formatter from the barrel
- * dragged the whole component library into those tests and broke them on the first `<template>` it hit. Same
- * split, and same reason, as `@intentic/ui`'s own `./path` and `./time` entry points.
- *
- * A SOURCE-level door, for in-repo extensions (whose code vite compiles into the app bundle) and their tests.
- * A git-installed bundle resolves its bare specifiers through the import map in index.html, which carries the
- * barrel alone, so nothing is exported here that the barrel does not also export, and a third-party author
- * reaching for `@intentic/extension-ui` is missing none of it. */
+// The kit's formatters, reachable without the component barrel: `index.ts` pulls in every .vue component, which breaks
+// an extension's node-environment tests that have no Vue plugin to parse SFCs with. A source-level door for in-repo
+// extensions and their tests; a git-installed bundle resolves through the import map instead, which carries the same
+// names.
 export {
     formatBytes,
     formatDate,

package/src/index.ts

@@ -1,82 +1,44 @@
-/* The UI kit extensions render with. This entrypoint is the package's ONE public surface (the repo's
- * re-export exception): a curated slice of the app design system (@intentic/ui) plus the PrimeVue
- * primitives extension views actually use. At runtime the kit is HOST-PROVIDED, the web app maps this module
- * into its import map (extension-host/hostModules.ts), so third-party bundles marking it external get the
- * shell's own component instances and theming; in-repo builtin extension packages bundle this same module and
- * land on the same instances. Export names are mirrored in ../names.mjs (shim generation + drift assertion).
- * Publishing a typed npm artifact for out-of-repo authors is a marketplace-phase task. */
+// The UI kit extensions render with: a curated slice of the app design system (@intentic/ui) plus the PrimeVue
+// primitives extension views use. Host-provided at runtime, mapped into the import map so third-party and in-repo
+// bundles share the same component instances.
 
-/* <Row> ships beside <RowGroup> because shipping the container WITHOUT the row is what made every extension
- * write its own: five views imported the group, found nothing to put in it, and hand-rolled a row body each.
- * The comment lives out here rather than beside the name because extensionUiNames.test.ts parses this brace
- * block for names, and reads a comment inside it as exports that do not exist.
- *
- * <SplitView> is here for exactly the same reason one level up: five screens are an index beside a body, and the
- * one implementation that had solved it (HubLayout) sat in the web app where no extension could import it. */
+// Documents `<Row>`/`<RowGroup>`/`<SplitView>` together, here rather than by name: extensionUiNames.test.ts parses
+// this block for names and would misread an attached comment as one.
 export {
-    /* <AgentRunButton> and its state ship because FOUR extensions start an agent for the user, pipelines,
-     * deployments, maintenance, acceptance, and each of them had reached a different answer about how you
-     * choose what it spends: three had no control at all and named the model in a tooltip, the fourth grew a
-     * chip of its own. That is the same divergence <SplitView> and <Row> were shipped to end, arriving on the
-     * one control in the app where getting it wrong costs money rather than pixels. `useAgentRunPick` is the
-     * half that needs `api.models` and takes it as an argument, so the kit stays free of the extension API. */
+    // `useAgentRunPick` takes `api.models` as an argument, so the kit itself stays free of the extension API.
     AgentRunButton,
     type AgentRunChoice,
     type AgentRunPicker,
     type ModelPicking,
     useAgentRunPick,
-    /* <AnchoredOverlay> ships because the alternative on this surface is PrimeVue's <Popover>, and six extension
-     * views had already reached for it. Popover measures and dismisses against the OPENER's window, so in a
-     * popped-out panel it opens off the bottom edge, over its own trigger, and cannot be clicked shut, the
-     * failure the kit's own tooltip directive exists to avoid. */
+    // Use over PrimeVue's Popover in a popped-out panel: Popover measures against the opener's window and can open
+    // off-screen, unclosable.
     AnchoredOverlay,
     Avatar,
-    /* <Button> MOVED OUT OF THE RAW PRIMITIVES BELOW, and that one line is why every extension got the press
-     * lock without touching a file of its own: a button whose click handler returns a promise now locks in the
-     * same tick it was pressed and draws the wait if it outlives a beat. Extension actions are the slowest in
-     * the app — a deployment, a workflow run, an agent — so they are exactly the ones an impatient second
-     * click used to fire twice. `vAction` ships beside it as the same behaviour for a hand-styled control:
-     * `<button v-action="run">`. Imported rather than left to the host's global registration on purpose, an
-     * unresolved directive is a button that silently does nothing, which is a worse failure than a missing
-     * tooltip and not one a reviewer would spot. */
+    // A click handler returning a promise auto-locks the button and shows a wait state; `vAction` is the same for a
+    // raw `<button v-action="run">`, imported explicitly since an unresolved directive silently does nothing.
     Button,
     vAction,
     BarChart,
     BottomSheet,
-    /* <BrandMark> ships because the approvals queue is the second surface to draw a platform as its brand (the
-     * capability cards were the first), and because its fallback is the part a hand-roll skips: a platform
-     * with no installed connector still has to render as SOMETHING, and the monogram is that something. */
+    // Renders a platform's brand; falls back to a monogram when no connector for it is installed.
     BrandMark,
     Card,
-    /* The window a copy has to go through. Missing from this surface is why git-history called
-     * `navigator.clipboard` directly and copying a commit SHA out of a POPPED-OUT panel silently did nothing:
-     * the module-global navigator belongs to the opener, whose document isn't focused, so the write rejects
-     * and every call site swallows it. */
+    // Use over raw `navigator.clipboard`: in a popped-out panel it belongs to the unfocused opener, so a direct write
+    // rejects.
     clipboardOf,
-    /* `browserOwnsClick` ships because every extension view that navigates has the same one-line decision to
-       make and no way to reach the app's answer: a row that is BOTH a link and a control must let a Ctrl/⌘,
-       Shift or Alt click belong to the browser, and do its own work only on the plain one. Three views had
-       hand-rolled a navigate() on a <button>, which is the version of that decision where the modifier keys
-       simply do not work. */
+    // A row that is both a link and a control: modifier clicks (Ctrl/⌘/Shift/Alt) fall through to the browser, a plain
+    // click acts.
     browserOwnsClick,
     appLink,
-    /* `openForwardedPort` ships because the Ports view is the third surface to wait on a freshly-minted preview
-     * hostname and the second to open one in a tab, and the two that had solved it (the preview panel's iframe
-     * gate, the terminal's Ctrl+click) both sat in the web app where no extension could import them. The
-     * duplicate was word-for-word, down to the sentence a user reads while DNS propagates. */
+    // Opens a freshly minted preview hostname in a tab once it is ready.
     openForwardedPort,
-    /* The two halves of a changed-file row ship together because they are always drawn together, and they ship
-     * at all for the reason <SplitView> did: the git-history extension is the seventh surface to draw one, and
-     * the six that had solved it all sat in the web app where no extension could import them. <ChangeStatusMark>
-     * carries the fixed-width cell that keeps a column of paths aligned whatever letter lands in it, the detail
-     * a hand-rolled copy gets subtly wrong. */
+    // `ChangeStatusMark` is fixed-width, so a column of paths stays aligned whatever status letter lands in it.
     ChangeStatusMark,
     type ChangeStatus,
     ui,
     Code,
-    /* <CodeField> ships beside <Code> because shipping the reader WITHOUT the writer is what made a note pane
-     * put a bare grey <textarea> next to a coloured block of the very same file: the kit had no way
-     * to say "this text, in its own colours, with a caret in it". */
+    // The editable counterpart to `Code`: syntax-coloured text with a caret in it.
     CodeField,
     ConfirmDialog,
     ContextMenu,
@@ -88,79 +50,47 @@ export {
     type DagEdge,
     type DagNode,
     DiffStat,
-    /* <DisclosureRow> ships for the reason <Row> itself does, one turn of the screw further on: shipping the
-     * row WITHOUT the expandable row is what made SIX extensions build their own — activity, maintenance,
-     * acceptance (twice), automations, deployments, pipelines, preview — and no two of them drew the same
-     * chevron, indented the opened block to the same column, or painted an open row the same colour. The
-     * preview extension's ports list went furthest and used an `(i)` as the toggle, thirty pixels under a real
-     * <InfoHint> whose `(i)` is a hover card: one glyph, two behaviours, one screen. */
+    // An expandable row; don't reuse `(i)` as its toggle glyph, `<InfoHint>` already uses `(i)` for a hover card.
     DisclosureRow,
     FilterBar,
     Icon,
     type IconName,
     ImageView,
-    /* <InfoDialog> and <InfoTable> ship beside <ConfirmDialog> and <Row> for the reason everything else here
-     * does: an extension with something to EXPLAIN rather than confirm, or a block of label→value facts to lay
-     * out, would otherwise hand-roll a dialog shell and a two-column grid, and the grid is where a hand-roll
-     * drifts, because keeping the value column aligned across rows is the whole of it. */
+    // For explaining, not confirming, or laying out label→value facts; keeps the value column aligned across rows.
     InfoDialog,
     InfoHint,
     InfoTable,
     isRenderableImage,
     Markdown,
+    // An editable markdown document (author-facing), unlike `Markdown`'s read-only render.
+    MarkdownDocument,
     MarkdownFigure,
-    /* <Modal> ships for the reason <ConfirmDialog> and <InfoDialog> already do, and it is the one they were
-     * both missing: an extension whose dialog is neither a confirm nor an explainer had nothing to reach for
-     * but PrimeVue's Dialog and a width typed into a style attribute, which is exactly how the app itself
-     * ended up with thirteen widths and one viewport clamp between seventeen dialogs. */
+    // For a dialog that is neither a confirm nor an explainer; clamps width to the viewport, unlike a raw PrimeVue
+    // Dialog.
     Modal,
     type NavGroup,
     NavRail,
-    /* <NoteEditor> and `useNoteDraft` ship because "a pane that reads a markdown file, lets somebody correct it
-     * and lets them delete it" is a shape an extension arrives at over and over, and the first two that did
-     * built the same thing twice: the same Copy/Edit/Delete cluster, the same Cancel/Save pair, the same
-     * in-place confirmation, the same draft-or-file binding, the same read-and-write-on-one-surface rule. They
-     * had already drifted in the ways a second copy does: one cleared its confirmation when a write failed and
-     * the other did not, and NEITHER caught a failing write, so the error strip filled in from the mutation
-     * while the click handler's promise rejected into the console. The component is the chrome and the
-     * composable is the lifecycle, separately, because what a note LOOKS like past the frame is exactly where
-     * two panes differ. */
+    // `NoteEditor` is the chrome, `useNoteDraft` the lifecycle, kept separate since a note's look past the frame
+    // differs by pane.
     NoteEditor,
     type NoteDraft,
     type NoteDraftOptions,
     useNoteDraft,
-    /* And the map those drafts live in, for the same pair of callers: the lifecycle deliberately does not own
-     * the ref (an unsaved edit has to outlive the pane that shows it), so both views had written the same
-     * keyed store above it, down to the `undefined` deletes rule the picker's "Unsaved" reads. */
+    // A keyed store of drafts that must outlive the pane showing them; deleting a key (`undefined`) is what a picker's
+    // "Unsaved" reads.
     useKeyedDraft,
-    /* <NoticeStack> and its model ship beside <ConfirmDialog> for the same reason <InfoDialog> does: a view
-     * with several async actions needs somewhere for their failures to land that isn't one action's own row,
-     * and a hand-rolled error strip is the first thing to disagree with the app's about tone and dismissal.
-     *
-     * <Notice>. THE SINGLE ONE, was missing from that shipment, and it is the same mistake <Row>/<RowGroup>
-     * and <PageAction>/<PageHeader> each record one release earlier: the container went out without the thing
-     * that goes in it. Notice.vue's own comment says every view that hand-rolled `ui.alertDanger()` around an
-     * interpolated error string renders it instead, "which is what makes the app's failures sound like one
-     * product rather than like sixty throw sites", and the app took that sweep, 107 call sites of it. The
-     * extensions could not: the kit handed out the stack and kept the row, so thirteen of them went on
-     * hand-rolling the strip. Most of a view's failures are ONE at a time; the stack is the rarer case. */
+    // `NoticeStack` holds failures from several async actions; `Notice` is the single one, for the common one-at-a-time
+    // case.
     type NoticeModel,
     type NoticeTone,
     type NoticeAction,
     Notice,
     NoticeStack,
     Page,
-    /* <PageAction> ships beside <PageHeader> for the same reason <Row> ships beside <RowGroup>: handing out the
-     * container without the thing that goes in it is what made every view invent one. Five extensions filled
-     * `#actions` with a raw PrimeVue <Button> and picked a different cell of its variant matrix each time. */
     PageAction,
     PageHeader,
     ScrollFrame,
-    /* <PersonaFace> ships because the TWO surfaces in the whole app where you choose a persona are both out
-     * here, an automation's "Runs as" and a workflow step's "Acts as", and neither could reach the drawing
-     * every surface that merely LISTS a persona already uses. So the one screen where you are picking a person
-     * by sight was the one screen showing a line of text. It is exported alongside <Picker>'s own `face` option
-     * field, which is what most callers actually want: hand the row a persona and the picker draws it. */
+    // Also reachable via `Picker`'s `face` option: hand it a persona and the picker draws it.
     PersonaFace,
     type PersonaLike,
     Picker,
@@ -168,24 +98,15 @@ export {
     type PickerOption,
     type PickerOptions,
     ProgressRing,
-    /* <RepoRail> ships for the reason <SplitView> did, one level in: two extensions scope a workspace-wide
-     * board to one repository, maintenance and pipelines, and both had written the same column. Same pinned
-     * "All repositories" row outside every group, same one-number-per-row rule with the second fact as its
-     * colour, same swap to a <Picker> at the width the split folds at. What differs between them is the report
-     * behind it, which is why the rows arrive as data. */
+    // A workspace board scoped to one repo; always includes a pinned "All repositories" row outside the groups.
     RepoRail,
     type RepoRailAll,
     type RepoRailGroup,
     type RepoRailRow,
-    /* The writing field and the drag seam ship for the same reason <SplitView> did: an extension view that
-     * wants prose typeset as a document, or a pane the reader can size, would otherwise hand-roll one, and
-     * both recipes have a failure mode (a replica that disagrees with its field; a drag bound to the window)
-     * that is invisible until it is in front of somebody. */
+    // Prose typeset as a document (`ProseField`) and a pane the reader can resize (`ResizeSeam`).
     ProseField,
     ResizeSeam,
-    /* <ResponsiveOverlay> is the one to reach for over <AnchoredOverlay> above whenever the panel is a MENU: it
-     * is the same anchored box on desktop and a thumb-reachable sheet on a phone, behind one open flag. Extension
-     * views are read on both, and a popover pinned to a 24px trigger is not usable on a touch screen. */
+    // Use over `AnchoredOverlay` for a menu: anchored on desktop, a thumb-reachable sheet on a phone, one open flag.
     ResponsiveOverlay,
     Row,
     RowGroup,
@@ -193,18 +114,10 @@ export {
     SegmentedControl,
     seriesColor,
     sinceOf,
-    /* The gate <SkeletonRows> and every hand-drawn outline go behind. It ships WITH the outline rather than
-     * after it, because the three extensions that already drew one drew it ungated: a placeholder that flashes
-     * for 90ms on a warm read is worse than no placeholder at all, and that is not a thing anybody notices in
-     * the screenshot they ship. See its note in the kit for the two thresholds. */
+    // Gates a skeleton placeholder so a flash on a fast read never shows; see its own note in the kit for the two
+    // thresholds.
     useLoadingReveal,
-    /* <SkeletonRows> ships beside <RowGroup> for the third time this file makes the argument: the container
-     * without the WAIT is what made three extensions write their own. Pipelines, deployments and maintenance
-     * each hand-rolled a placeholder board, and the row-shaped half of all three is this component, same
-     * bars, same widths walked in order, same `aria-hidden` under the caller's one status region. What they
-     * could not get right by hand is the part that does not show up in a screenshot: a bar is thinner than the
-     * text it replaces, so an outline built out of divs is shorter than the list that lands and the page jumps
-     * as it fills. This one renders REAL <Row>s, so it inherits the tier's padding and keeps the height. */
+    // Renders real `<Row>`s rather than divs, so its height matches what replaces it and the page doesn't jump.
     SkeletonRows,
     SplitView,
     StatStrip,
@@ -214,43 +127,29 @@ export {
     TIME_WINDOWS,
     type TimeWindow,
     timeWindowWords,
-    /* Whether the <SplitView> above has folded its index above its body. What a rail asks before swapping itself
-     * to a compact control, so the two halves of one screen change shape at one width. Outside a split it falls
-     * back to the device, which is the only narrow case left. */
+    // Whether the enclosing `<SplitView>` has folded to compact; outside a split it falls back to device width.
     useCompact,
     useDevice,
-    /* Arrow keys / Home / End / Enter over a list, with the wrap-around and the scroll-into-view already
-     * decided. Ships because a keyboard-navigable list is the shape half these views are, and the parts a
-     * hand-roll leaves out (wrapping at the ends, keeping the active row in view) are invisible on a mouse. */
+    // Arrow/Home/End/Enter navigation over a list, with wrap-around and scroll-into-view handled.
     useListNavigation,
-    /* <useNow> and <useAsyncAction> ship because the drafts queue was the first extension with a live countdown
-     * and a page of mutations, the two shapes every such view hand-rolls, one interval and one busy flag at a
-     * time, each subtly wrong (a clock that keeps ticking with nothing on screen; a double-click firing twice). */
+    // A ticking clock (`useNow`) and a busy/error flag for one mutation at a time (`useAsyncAction`).
     useNow,
     errorMessage,
     noticeFrom,
     noticeOf,
     useAsyncAction,
-    /* "Is my own element too narrow for this layout", the question every extension view actually means, since it
-     * renders into a pane the reader can drag to half its width, not into the window. */
+    // Whether the element itself is narrow, not the window; views render into a resizable pane.
     useNarrow,
-    /* Where the reader left a narrowing rail. Ships for the reason <SplitView> did: three extension views grew
-     * the same index column, all three keep the pick in the URL, and all three lost it the moment you clicked the
-     * tile again, because a tile opens a view at its bare address. Solving that per extension would be three
-     * copies of one rule about what a link means versus what a memory is allowed to guess. */
+    // Remembers a rail's last pick across reopening a tile, which otherwise opens at the view's bare address.
     useRailMemory,
-    /* The other half of `scroll="page"`. A view whose rail SELECTS something (a note, a package page) hands the
-     * page scrollport a position that stops meaning anything the moment the selection moves, and every such
-     * view would otherwise re-derive the same answer: find the shell's scroller, put it back at the top. */
+    // Resets the page scrollport to top when a rail selection changes; the other half of `scroll="page"`.
     useScrollReset,
-    /* And what the next pinned thing under it has to clear, since a page-scrolling view that pins a filter bar
-     * over its content is the shape three of these sections now are. */
+    // Height the next pinned element must clear, for a page-scrolling view stacking pinned bars.
     type StickyTop,
     useStickyTop,
     useTheme,
 } from "@intentic/ui";
-// Also reachable as `@intentic/extension-ui/format`, see the note there for why an extension's pure logic
-// wants them without the components attached.
+// Also reachable as `@intentic/extension-ui/format`, without the components attached.
 export {
     formatBytes,
     formatDate,
@@ -263,10 +162,8 @@ export {
     freshness,
     timeAgo,
 } from "./format.js";
-/* The figure vocabulary that <Markdown> renders from prose and <MarkdownFigure> renders from data. Types only,
- * an extension needs them to BUILD a figure out of facts it already holds (a dependency graph, a staleness
- * tally) rather than round-tripping through markdown to draw one. The parser and the document splitter stay out
- * of the kit: they are the prose surface's job, and <Markdown> already does it. */
+// Types only, so an extension can build a figure straight from facts it holds instead of round-tripping through
+// markdown. The parser and document splitter stay in `<Markdown>`, not here.
 export type {
     BarsFigure,
     BarsFigureItem,
@@ -279,15 +176,9 @@ export type {
     StatsFigure,
     StatsFigureItem,
 } from "@intentic/ui/markdown";
-/* The raw primitives, kept deliberately short. Handing out a primitive the KIT already wraps is how an
- * extension screen ends up wearing OS chrome next to the app's own: `Select` and `InputText` used to ship here
- * and four views took them, so a dropdown with a different focus ring sat beside <Picker> and a text field with
- * different padding beside `ui.input`. Those two are gone: <Picker> and `ui.input()` are the spellings.
- * <Dialog> was the third, and it is gone for the same reason: it stayed "until the kit has a general dialog
- * shell", six extension views took it, and every one of them typed its own width into a style attribute with
- * no viewport clamp, the exact spread that <Modal> above now exists to end. The shell is here, so the raw one
- * is not. <Popover> stays only because <ResponsiveOverlay>/<AnchoredOverlay> do not yet cover every menu shape,
- * and it is on the same clock: those two are the ones that open in the right window when a panel is popped out. */
+// Raw PrimeVue primitives kept deliberately few: prefer `Picker`/`ui.input()`/`Modal` over
+// `Select`/`InputText`/`Dialog`.
+// `Popover` stays only where `AnchoredOverlay`/`ResponsiveOverlay` don't yet cover a menu shape.
 export { default as Checkbox } from "primevue/checkbox";
 export type { MenuItem } from "primevue/menuitem";
 export { default as Popover } from "primevue/popover";