@mythicalos/ui-core 0.2.2 → 0.3.1

package/dist/index.d.ts

@@ -1,9 +1,15 @@
 export { buttonClass, type BtnVariant, type BtnState } from "./logic/button.js";
 export { nextPollDelay, makePollEpochGuard, runPollTick, shouldResetEpoch, POLL_JITTER_RATIO, POLL_BACKOFF_CAP_MS, type PollResult, type PollEpochGuard, type PollTickIO, } from "./logic/poll.js";
 export { typedNameMatches, BULLET_ICON, type DialogBullet } from "./logic/dialog.js";
+export { POPOVER_CARET, POPOVER_CHECK, POPOVER_GAP_PX, POPOVER_BREATHING_PX, POPOVER_EMPTY_VALUE, POPOVER_DEFAULT_POSITION, POPOVER_CLASS, POPOVER_DECORATIVE_ARIA, POPOVER_SEPARATOR_ARIA, resolvePopoverPlacement, resolvePopoverAlign, resolvePopoverPosition, samePopoverPosition, popoverTriggerClass, popoverPanelClass, popoverItemClass, popoverIds, popoverTriggerAria, popoverPanelAria, popoverMenuAria, popoverItemAria, popoverTriggerKeyAction, popoverPanelKeyAction, popoverKeyHandled, popoverAppliesToFocus, edgePopoverIndex, stepPopoverIndex, initialPopoverIndex, resolvePopoverIndex, popoverTriggerText, popoverHasSlotContent, type PopoverItem, type PopoverPlacement, type PopoverAlign, type PopoverPosition, type PopoverRect, type PopoverSize, type PopoverViewport, type PopoverTriggerState, type PopoverIds, type PopoverTriggerAria, type PopoverPanelAria, type PopoverMenuAria, type PopoverItemAria, type PopoverTriggerKeyAction, type PopoverPanelKeyAction, type PopoverTriggerText, type PopoverTriggerTextOptions, } from "./logic/popover.js";
 export { composeToastText, TOAST_SEP, type ToastStatus, type ToastSpec, type ToastBus, } from "./logic/toast.js";
 export { gaugeTone, gaugeGeom, type GaugeGeom } from "./logic/gauge.js";
 export { chipClass, statusLineClass, bannerClass, BANNER_ICON, type Tone, type ChipTone, type StatusTone, type BannerTone, } from "./logic/tone.js";
 export { saveBarNote, saveBarDirty, saveBarClass, SAVE_BAR_PARTS, SAVE_BAR_SEP, SAVE_BAR_DISCARD_LABEL, SAVE_BAR_SAVE_LABEL, type SaveBarNote, } from "./logic/save-bar.js";
 export { statTilesClass, statTileClass, STAT_TILE_PARTS, formatStatCompact, formatStatCount, formatStatUsd, formatStatPercent, STAT_TILE_EMPTY, STAT_TILE_MINUS, type StatTile, type StatTileTone, } from "./logic/stat-tiles.js";
 export { gitFlags, hasGitStatus, gitBranchLabel, gitChipClass, gitFlagClass, gitChipNote, GIT_CHIP_PARTS, GIT_BRANCH_GLYPH, GIT_BRANCH_UNKNOWN, GIT_DETACHED_LABEL, GIT_CLEAN_LABEL, GIT_LOADING_NOTE, GIT_UNAVAILABLE_NOTE, GIT_STALE_LABEL, GIT_STALE_TITLE, type GitStatus, type GitFlag, type GitFlagTone, type GitChipState, } from "./logic/git-chip.js";
+export { deriveFileTreeRows, countFileRows, countLoadedFiles, classifyDirNode, repoBadges, isUsableEntryName, isUsableRootKey, MAX_TREE_DEPTH, NODE_GLYPH, CHEVRON_OPEN, CHEVRON_CLOSED, chevronGlyph, scopeGlyph, SCOPE_CARET, fileGlyph, isMarkdownName, NODE_ID_SEP, nodeId, splitNodeId, childRelPath, parentRelPath, ancestorRelPaths, BREADCRUMB_SEP, breadcrumbSegments, buildBreadcrumb, gitMarkTone, gitMarkLabel, gitMarkClass, previewBadge, previewBadgeClass, HONEST_STATUSES, isHonestStatus, honestNoteText, honestNoteClass, treeNoteClass, treeNoteRowClass, previewNoteText, previewNoteClass, previewBodyMode, previewMeta, formatFileSize, formatRelativeTime, SECONDS_THRESHOLD, MAX_INDENT_DEPTH, indentClass, dirRowClass, fileRowClass, badgeClass, scopeItemClass, type FileTreeMode, type FileNodeKind, type GitMark, type GitMarkTone, type FileTreeRootSpec, type FileTreeEntry, type DirState, type HonestStatus, type HonestSurface, type FilePreviewState, type FileRowBadge, type PreviewBadgeState, type PreviewBadge, type FileTreeDirRow, type FileTreeFileRow, type FileTreeNoteRow, type FileTreeRow, type DeriveFileTreeInput, type FileScopeOption, } from "./logic/file-explorer.js";
+export { ctxBand, ctxReading, ctxFillPct, ctxValueText, ctxNoteText, ctxMeterClass, ctxBarGeom, normalizeCtxThresholds, sessionStatus, sessionStatusClass, sessionStatusText, sessionCardIsStale, sessionCardStale, sessionCardClass, sessionAvatarInitial, sessionSubline, sessionSpineNodes, sessionSpineLabel, sessionSpineSavedText, sessionSpineSummary, spineNodeClass, CTX_THRESHOLDS_DEFAULT, CTX_UNKNOWN_TEXT, CTX_LABEL, CTX_BAR_SPAN, CTX_BAR_HEIGHT, CTX_BAR_VIEWBOX, CTX_BAR_TICK_WIDTH, SESSION_CARD_SEP, SESSION_STATUS_UNKNOWN, SESSION_AVATAR_UNKNOWN, SPINE_SAVED_UNKNOWN, SPINE_MAX_NODES, type CtxThresholds, type CtxBand, type CtxBarTick, type CtxBarGeom, type SessionLifecycle, type SessionActivity, type SessionStatusTone, type SessionStatusKey, type SessionStatus, type SessionStatusInput, type SessionSpine, type SpineNode, type SpineSummary, } from "./logic/session-card.js";
+export { DEFAULT_DELIVERY_CLASS, DELIVERY_CLASSES, DELIVERY_HINT, SEND_PLACEHOLDER, SEND_DISABLED_FALLBACK, SEND_BUTTON_LABEL, SENDBAR_CLASSES, canSend, clearDraftOnSend, deliveryClassButtonClass, deliveryClassLabel, keyAction, makeSendGate, resolveSend, sendBarClass, sendPlaceholder, showDeliveryHint, type DeliveryClass, type KeyAction, type SendGate, } from "./logic/sendbar.js";
+export { QUEUE_CANCEL_ASK, QUEUE_CANCEL_LABEL, QUEUE_CANCEL_NO, QUEUE_CANCEL_YES, QUEUE_EMPTY_COPY, QUEUE_LOADING_COPY, QUEUE_STALE_COPY, QUEUE_UNAVAILABLE_COPY, QUEUE_CLASSES, canCancelRow, cancelReducer, isFreshSource, queueBadgeClass, queueBadgeLabel, queueRowClass, queueStatusLabel, queueView, shouldDisarmCancel, unavailableText, type CancelEvent, type CancelState, type QueueItem, type QueueItemStatus, type QueueSource, type QueueUnavailableReason, type QueueView, } from "./logic/queue.js";
+export { ROW_SCOPE, TERM_CLASS, TERM_CLASSES, TERM_FAILED_COPY, TERM_LOADING_COPY, TERM_MISSING_COPY, TERM_NO_EVENTS_COPY, TERM_ROW_KINDS, TERM_STALE_COPY, TERM_STOP_KEY_HINT, TERM_STOP_LABEL, TERM_UNADDRESSABLE_COPY, TERM_WAKE_UNAVAILABLE_COPY, TURN_IDLE_COPY, TURN_IN_FLIGHT_COPY, ROW_COLLAPSE_LABEL, ROW_EXPAND_LABEL, currentWakeRows, expandLabel, historySegmentCaption, historyToggleLabel, isExpandable, lastBoundaryIndex, noiseShow, rowKey, rowKeys, scopedRowKeys, segmentKeys, shouldStopOnKey, sourceRows, stopButtonClass, termRowClass, termTitleText, transcriptView, turnCaption, uniqueKeys, visibleRows, type TermRow, type TermRowKind, type TermSource, type TermView, type TranscriptSegment, } from "./logic/terminal.js";

package/dist/index.js

@@ -4,6 +4,7 @@
 export { buttonClass } from "./logic/button.js";
 export { nextPollDelay, makePollEpochGuard, runPollTick, shouldResetEpoch, POLL_JITTER_RATIO, POLL_BACKOFF_CAP_MS, } from "./logic/poll.js";
 export { typedNameMatches, BULLET_ICON } from "./logic/dialog.js";
+export { POPOVER_CARET, POPOVER_CHECK, POPOVER_GAP_PX, POPOVER_BREATHING_PX, POPOVER_EMPTY_VALUE, POPOVER_DEFAULT_POSITION, POPOVER_CLASS, POPOVER_DECORATIVE_ARIA, POPOVER_SEPARATOR_ARIA, resolvePopoverPlacement, resolvePopoverAlign, resolvePopoverPosition, samePopoverPosition, popoverTriggerClass, popoverPanelClass, popoverItemClass, popoverIds, popoverTriggerAria, popoverPanelAria, popoverMenuAria, popoverItemAria, popoverTriggerKeyAction, popoverPanelKeyAction, popoverKeyHandled, popoverAppliesToFocus, edgePopoverIndex, stepPopoverIndex, initialPopoverIndex, resolvePopoverIndex, popoverTriggerText, popoverHasSlotContent, } from "./logic/popover.js";
 export { composeToastText, TOAST_SEP, } from "./logic/toast.js";
 export { gaugeTone, gaugeGeom } from "./logic/gauge.js";
 export { chipClass, statusLineClass, bannerClass, BANNER_ICON, } from "./logic/tone.js";
@@ -11,3 +12,25 @@ export { chipClass, statusLineClass, bannerClass, BANNER_ICON, } from "./logic/t
 export { saveBarNote, saveBarDirty, saveBarClass, SAVE_BAR_PARTS, SAVE_BAR_SEP, SAVE_BAR_DISCARD_LABEL, SAVE_BAR_SAVE_LABEL, } from "./logic/save-bar.js";
 export { statTilesClass, statTileClass, STAT_TILE_PARTS, formatStatCompact, formatStatCount, formatStatUsd, formatStatPercent, STAT_TILE_EMPTY, STAT_TILE_MINUS, } from "./logic/stat-tiles.js";
 export { gitFlags, hasGitStatus, gitBranchLabel, gitChipClass, gitFlagClass, gitChipNote, GIT_CHIP_PARTS, GIT_BRANCH_GLYPH, GIT_BRANCH_UNKNOWN, GIT_DETACHED_LABEL, GIT_CLEAN_LABEL, GIT_LOADING_NOTE, GIT_UNAVAILABLE_NOTE, GIT_STALE_LABEL, GIT_STALE_TITLE, } from "./logic/git-chip.js";
+// ── file explorer & markdown preview (ds/components-file-explorer) ──
+export { 
+// tree derivation
+deriveFileTreeRows, countFileRows, countLoadedFiles, classifyDirNode, repoBadges, isUsableEntryName, isUsableRootKey, MAX_TREE_DEPTH, 
+// glyphs
+NODE_GLYPH, CHEVRON_OPEN, CHEVRON_CLOSED, chevronGlyph, scopeGlyph, SCOPE_CARET, fileGlyph, isMarkdownName, 
+// path + breadcrumb composition
+NODE_ID_SEP, nodeId, splitNodeId, childRelPath, parentRelPath, ancestorRelPaths, BREADCRUMB_SEP, breadcrumbSegments, buildBreadcrumb, 
+// git marks
+gitMarkTone, gitMarkLabel, gitMarkClass, previewBadge, previewBadgeClass, 
+// honest states
+HONEST_STATUSES, isHonestStatus, honestNoteText, honestNoteClass, treeNoteClass, treeNoteRowClass, previewNoteText, previewNoteClass, previewBodyMode, previewMeta, 
+// formatting
+formatFileSize, formatRelativeTime, SECONDS_THRESHOLD, 
+// class strings
+MAX_INDENT_DEPTH, indentClass, dirRowClass, fileRowClass, badgeClass, scopeItemClass, } from "./logic/file-explorer.js";
+// ── session-card (design registry `session-card` v1) ──
+export { ctxBand, ctxReading, ctxFillPct, ctxValueText, ctxNoteText, ctxMeterClass, ctxBarGeom, normalizeCtxThresholds, sessionStatus, sessionStatusClass, sessionStatusText, sessionCardIsStale, sessionCardStale, sessionCardClass, sessionAvatarInitial, sessionSubline, sessionSpineNodes, sessionSpineLabel, sessionSpineSavedText, sessionSpineSummary, spineNodeClass, CTX_THRESHOLDS_DEFAULT, CTX_UNKNOWN_TEXT, CTX_LABEL, CTX_BAR_SPAN, CTX_BAR_HEIGHT, CTX_BAR_VIEWBOX, CTX_BAR_TICK_WIDTH, SESSION_CARD_SEP, SESSION_STATUS_UNKNOWN, SESSION_AVATAR_UNKNOWN, SPINE_SAVED_UNKNOWN, SPINE_MAX_NODES, } from "./logic/session-card.js";
+// ── terminal set (ds/components-terminal v2): terminal · queue-row · send-bar ──
+export { DEFAULT_DELIVERY_CLASS, DELIVERY_CLASSES, DELIVERY_HINT, SEND_PLACEHOLDER, SEND_DISABLED_FALLBACK, SEND_BUTTON_LABEL, SENDBAR_CLASSES, canSend, clearDraftOnSend, deliveryClassButtonClass, deliveryClassLabel, keyAction, makeSendGate, resolveSend, sendBarClass, sendPlaceholder, showDeliveryHint, } from "./logic/sendbar.js";
+export { QUEUE_CANCEL_ASK, QUEUE_CANCEL_LABEL, QUEUE_CANCEL_NO, QUEUE_CANCEL_YES, QUEUE_EMPTY_COPY, QUEUE_LOADING_COPY, QUEUE_STALE_COPY, QUEUE_UNAVAILABLE_COPY, QUEUE_CLASSES, canCancelRow, cancelReducer, isFreshSource, queueBadgeClass, queueBadgeLabel, queueRowClass, queueStatusLabel, queueView, shouldDisarmCancel, unavailableText, } from "./logic/queue.js";
+export { ROW_SCOPE, TERM_CLASS, TERM_CLASSES, TERM_FAILED_COPY, TERM_LOADING_COPY, TERM_MISSING_COPY, TERM_NO_EVENTS_COPY, TERM_ROW_KINDS, TERM_STALE_COPY, TERM_STOP_KEY_HINT, TERM_STOP_LABEL, TERM_UNADDRESSABLE_COPY, TERM_WAKE_UNAVAILABLE_COPY, TURN_IDLE_COPY, TURN_IN_FLIGHT_COPY, ROW_COLLAPSE_LABEL, ROW_EXPAND_LABEL, currentWakeRows, expandLabel, historySegmentCaption, historyToggleLabel, isExpandable, lastBoundaryIndex, noiseShow, rowKey, rowKeys, scopedRowKeys, segmentKeys, shouldStopOnKey, sourceRows, stopButtonClass, termRowClass, termTitleText, transcriptView, turnCaption, uniqueKeys, visibleRows, } from "./logic/terminal.js";

package/dist/logic/file-explorer.d.ts

@@ -0,0 +1,374 @@
+/** Which tree the rail is drawing. See the header — the two differ in substance, not styling. */
+export type FileTreeMode = "all-mounts" | "project";
+/** What a row IS, once the mode + depth have been taken into account. */
+export type FileNodeKind = "mount" | "repo" | "dir" | "file";
+/** A git worktree mark, per the card's legend (`M` warn · `A` ok) plus the marks a real
+ *  `git status` also produces. */
+export type GitMark = "M" | "A" | "D" | "R" | "?";
+/** The tone axis for a mark. Never "error": an uncommitted file is not a failure. */
+export type GitMarkTone = "warn" | "ok" | "muted";
+/** One root of the tree. In "all-mounts" mode these are the bind mounts; in "project" mode they are
+ *  the selected project's repos. `primary` / `projectCount` are project-mode badge inputs and are
+ *  ignored in all-mounts mode (a bind mount is not a repo and has no project membership). */
+export interface FileTreeRootSpec {
+    key: string;
+    label: string;
+    /** Project mode: this repo is its project's primary repo. */
+    primary?: boolean;
+    /** Project mode: how many projects reference this repo. Only reported when > 1 (shared). */
+    projectCount?: number;
+}
+/** One entry inside a directory listing. `repo` lets a caller that actually KNOWS whether a
+ *  directory is a git repo say so; when it is undefined the card's structural rule applies (see
+ *  `classifyDirNode`). */
+export interface FileTreeEntry {
+    name: string;
+    kind: "dir" | "file";
+    repo?: boolean;
+}
+/** The state of ONE directory's listing. `unavailable` and a loaded-but-`entries: []` listing are
+ *  two of the four honest states — an unreadable directory is not the same claim as an empty one,
+ *  and the tree must never collapse them together. */
+export type DirState = {
+    status: "loading";
+} | {
+    status: "unavailable";
+} | {
+    status: "loaded";
+    entries: readonly FileTreeEntry[];
+    truncated?: boolean;
+};
+/** The four honest states, named. Exported as a value so a caller (and this package's tests) can
+ *  enumerate them rather than restate the list. */
+export type HonestStatus = "unavailable" | "empty" | "too-large" | "binary";
+export declare const HONEST_STATUSES: readonly HonestStatus[];
+/** Whether a string names one of the four honest states. */
+export declare function isHonestStatus(value: unknown): value is HonestStatus;
+/** What the preview pane has to show. `text` is the only branch carrying content; the other four
+ *  non-loading branches are the honest states. The caller ADAPTS its own file-content source into
+ *  this union — the atom never fetches (see the package README / the component's props). */
+export type FilePreviewState = {
+    status: "loading";
+} | {
+    status: "unavailable";
+} | {
+    status: "empty";
+} | {
+    status: "too-large";
+    bytes?: number;
+} | {
+    status: "binary";
+    bytes?: number;
+} | {
+    status: "text";
+    text: string;
+    bytes?: number;
+    mtime?: number;
+};
+/** The directory glyph per node kind. A plain sub-directory deliberately carries NO glyph: the
+ *  chevron already renders "▸", and repeating it would draw "▸ ▸ name". The bindings still emit the
+ *  (empty) glyph cell so every row's name stays on one vertical rule. */
+export declare const NODE_GLYPH: Record<"mount" | "repo" | "dir", string>;
+/** The disclosure chevron — the card's ▾ / ▸. The WHOLE ROW is the hit target (the bindings render
+ *  one button per row); this is the affordance, never a separate control. */
+export declare const CHEVRON_OPEN = "\u25BE";
+export declare const CHEVRON_CLOSED = "\u25B8";
+export declare function chevronGlyph(open: boolean): string;
+/** The scope picker’s disclosure caret. Lives here, not in the bindings, so the two cannot drift. */
+export declare const SCOPE_CARET = "\u2304";
+/** The scope-picker glyph for a mode: ⌂ for all-mounts, ◈ for a project. */
+export declare function scopeGlyph(mode: FileTreeMode): string;
+/** A mono type glyph for a FILE row: `#` markdown · `{}` json · `·` anything else. */
+export declare function fileGlyph(name: string): string;
+/** Whether a name should render as MARKDOWN rather than as plain mono text. */
+export declare function isMarkdownName(name: string): boolean;
+/**
+ * A stable identity for one node: root key + relative path, joined on NUL.
+ *
+ * The join is unambiguous — and `splitNodeId` is an exact inverse — precisely WHEN neither field
+ * contains the separator. That is not assumed: `deriveFileTreeRows` screens every root key through
+ * `isUsableRootKey` and every entry name through `isUsableEntryName`, so no id the component emits
+ * can round-trip lossily. A caller building an id by hand from an UNSCREENED root key is outside
+ * that guarantee (a key containing the separator splits back into a different pair) — screen with
+ * `isUsableRootKey` first, exactly as the walk does.
+ */
+export declare const NODE_ID_SEP = "\0";
+export declare function nodeId(rootKey: string, relPath: string): string;
+/** The inverse of `nodeId`, split at the FIRST NUL. A string without one is not a node id and
+ *  yields null rather than a half-parsed pair. */
+export declare function splitNodeId(id: string): {
+    rootKey: string;
+    relPath: string;
+} | null;
+/** Join a parent relative path with a child name (at a root, the bare name). */
+export declare function childRelPath(relPath: string, name: string): string;
+/** Split a relative path into its parent path and its own name
+ *  (`"a/b/c"` ⇒ `{"a/b","c"}` · `"c"` ⇒ `{"","c"}`). */
+export declare function parentRelPath(relPath: string): {
+    parentRel: string;
+    name: string;
+};
+/** The ancestor DIRECTORIES of a relative file path, root-first and including the root itself:
+ *  `"docs/api/x.md"` ⇒ `["", "docs", "docs/api"]`. */
+export declare function ancestorRelPaths(relPath: string): string[];
+/** The card's breadcrumb separator — a wide-spaced "›". */
+export declare const BREADCRUMB_SEP = "  \u203A  ";
+/** Breadcrumb segments from a root label down through the path. The ROOT IS ALWAYS INCLUDED (the
+ *  card: "Breadcrumb always includes the project root"), so a bare filename can never read as
+ *  belonging to nowhere. */
+export declare function breadcrumbSegments(rootLabel: string, relPath: string): string[];
+/** The breadcrumb as one string. */
+export declare function buildBreadcrumb(rootLabel: string, relPath: string): string;
+/** Classify a DIRECTORY node for the active mode.
+ *
+ *  · project mode    — depth 0 IS a repo (the card: the project's repos ARE the roots); deeper
+ *                      directories are plain directories.
+ *  · all-mounts mode — depth 0 is a bind MOUNT; the level immediately beneath it is where git repos
+ *                      live, so depth 1 classifies as "repo"; deeper is a plain directory.
+ *
+ *  `entryRepo` is the caller's own knowledge and always wins when supplied: a data source that can
+ *  actually tell a repo from an ordinary folder should say so, and a depth-1 directory that is NOT a
+ *  repo then renders as the plain directory it is. When it is undefined the card's structural rule
+ *  above applies. Pure. */
+export declare function classifyDirNode(mode: FileTreeMode, depth: number, entryRepo?: boolean): "mount" | "repo" | "dir";
+/** A pill on a repo row. `accent` = a claim about THIS project (primary); `muted` = a neutral fact
+ *  about sharing. */
+export interface FileRowBadge {
+    text: string;
+    tone: "accent" | "muted";
+}
+/** The badges for a repo row — PROJECT MODE ONLY, because both facts are statements about project
+ *  membership and neither is meaningful for a bind mount.
+ *
+ *  · `primary`      — this repo is its project's primary repo.
+ *  · `N projects`   — this repo is referenced by N (> 1) projects, i.e. it is shared.
+ *
+ *  Both can hold at once (a shared repo that is also primary here), and both are then rendered: they
+ *  are independent facts, and suppressing the sharing count would hide it exactly where it matters
+ *  most. Pure. */
+export declare function repoBadges(root: FileTreeRootSpec, mode: FileTreeMode): FileRowBadge[];
+export declare function badgeClass(tone: FileRowBadge["tone"]): string;
+/** The tone for a mark, per the card's legend (`M` warn · `A` ok) extended to the marks a real
+ *  status also yields. A RENAME reduces to one glyph whether it is staged or unstaged, so it takes
+ *  the conservative `warn` rather than a false all-good green for still-uncommitted work. */
+export declare function gitMarkTone(mark: GitMark): GitMarkTone;
+/** A human word for a mark — the accessible name, because a bare "M" is opaque to a screen reader. */
+export declare function gitMarkLabel(mark: GitMark): string;
+/** The mono 10px mark cell's class. */
+export declare function gitMarkClass(mark: GitMark): string;
+/** The preview header's status pill. `clean` is only ever an HONEST clean — the caller passes it
+ *  when the file's repo genuinely reported no change for it. When there is no git knowledge at all
+ *  the caller passes null and NO pill renders, because a fabricated "unchanged" would be a claim
+ *  nobody proved. */
+export type PreviewBadgeState = {
+    kind: "mark";
+    mark: GitMark;
+} | {
+    kind: "clean";
+} | null;
+export interface PreviewBadge {
+    text: string;
+    tone: GitMarkTone;
+}
+export declare function previewBadge(state: PreviewBadgeState): PreviewBadge | null;
+export declare function previewBadgeClass(tone: GitMarkTone): string;
+/** Human file size — "512 B", "14.2 KB". A negative or non-finite input reads "0 B" rather than
+ *  rendering NaN. Pure. */
+export declare function formatFileSize(bytes: unknown): string;
+/**
+ * Relative time — "2m ago". `now` is injected so this stays pure and testable. A future timestamp
+ * clamps to "0s ago" rather than rendering a negative age. Pure.
+ *
+ * Seconds-vs-milliseconds is disambiguated by magnitude, with the threshold at 1e11 rather than the
+ * 1e12 some sibling surfaces use. 1e12 ms is 2001-09-09, so under that rule ANY millisecond
+ * timestamp older than 2001 is mistaken for seconds, multiplied by 1000 into the far future, and
+ * then clamped — reporting a genuinely old file as "0s ago", i.e. a plausible-looking lie. At 1e11
+ * the seconds branch still covers every second-timestamp up to the year 5138, while millisecond
+ * timestamps are read correctly all the way back to 1973.
+ */
+export declare const SECONDS_THRESHOLD = 100000000000;
+export declare function formatRelativeTime(t: unknown, now?: number): string;
+/** Where an honest state is being reported. The SENTENCE differs ("this directory" vs "this file");
+ *  the tone never does. */
+export type HonestSurface = "dir" | "file";
+/**
+ * The sentence for an honest state. Plain, specific, and never apologetic — each says what IS true,
+ * not what went wrong. `bytes` is woven in for the two size-bearing states when it is known.
+ */
+export declare function honestNoteText(status: HonestStatus, surface?: HonestSurface, bytes?: number): string;
+/**
+ * The class for an honest-state note. Every one of the four gets its OWN modifier (so each is
+ * distinctly renderable and independently styleable) while the base class carries a single,
+ * deliberately INFORMATIONAL tone.
+ *
+ * There is no `--error` / `--warn` variant here, and that is the point: an unreadable directory, an
+ * empty file, an oversized file and a binary file are all ordinary things a filesystem contains. The
+ * component reports them; it does not accuse. Pure.
+ */
+export declare function honestNoteClass(status: HonestStatus): string;
+/** The note class for the tree's two NON-honest informational rows (an in-flight listing and a
+ *  server-truncated one). Same neutral base — neither is a failure either. */
+export declare function treeNoteClass(status: "loading" | "truncated"): string;
+/** A note row INSIDE the tree — the note class plus the depth indent, so a note lines up under the
+ *  node it describes instead of sitting flush against the rail. The indent is composed here rather
+ *  than inside `honestNoteClass` because the same honest-state classes are reused by the PREVIEW
+ *  pane, where a tree indent would be meaningless. */
+export declare function treeNoteRowClass(status: "loading" | "truncated" | HonestStatus, depth: number): string;
+/** The preview body's sentence for any state that has no content to render, or null for `text`
+ *  (where the real content renders instead). */
+export declare function previewNoteText(state: FilePreviewState): string | null;
+/** The preview body note's class, or null for `text`. */
+export declare function previewNoteClass(state: FilePreviewState): string | null;
+/**
+ * The size/mtime the preview HEADER should show. The state's own values win where it carries them —
+ * they describe the bytes actually on screen, so the header can never show a stale size next to
+ * fresh content — and the caller's listing values (`fallback`) fill the rest.
+ *
+ * `too-large` / `binary` carry a size but no mtime (nothing was read), so the mtime falls back to
+ * the listing's. A value that is genuinely unknown stays `undefined` rather than becoming a zero the
+ * formatter would render as a real "0 B" / "56y ago". Pure.
+ */
+export declare function previewMeta(state: FilePreviewState, fallback?: {
+    bytes?: number;
+    mtime?: number;
+}): {
+    bytes?: number;
+    mtime?: number;
+};
+/**
+ * How the preview should render the body — the SINGLE decision both bindings follow, so neither
+ * re-derives it and the two cannot drift:
+ *   · "note"     — there is no content to show (loading, or any of the honest states);
+ *   · "markdown" — a markdown name AND a renderer to hand it to;
+ *   · "plain"    — everything else, including a markdown file with NO renderer supplied.
+ *
+ * `hasMarkdownRenderer` is part of the decision rather than a binding-side afterthought: markdown
+ * rendering is the caller's to provide, and without it the honest outcome is plain text — never the
+ * component inventing a renderer or injecting raw HTML.
+ */
+export declare function previewBodyMode(name: string, state: FilePreviewState, hasMarkdownRenderer?: boolean): "markdown" | "plain" | "note";
+/** Depth-class ceiling — rows deeper than this share the last indent step rather than growing the
+ *  stylesheet without bound. */
+export declare const MAX_INDENT_DEPTH = 10;
+/** Hard ceiling on TRAVERSAL depth. Unlike `MAX_INDENT_DEPTH` (a purely visual cap) this bounds the
+ *  recursion itself, so no caller-supplied listing can walk the derivation into a stack overflow. */
+export declare const MAX_TREE_DEPTH = 64;
+/**
+ * Whether an entry name is structurally usable as one path segment.
+ *
+ * An EMPTY name is the dangerous one: `childRelPath("", "")` returns `""`, which is the ROOT's own
+ * relative path — so an expanded root listing itself as a nameless directory would re-enter the same
+ * node id forever. A name containing "/" or a NUL is rejected for the same class of reason: it would
+ * silently compose a path that addresses a different node than the one listed (and NUL would break
+ * `nodeId`'s separator outright). None of these can name a real filesystem entry.
+ */
+export declare function isUsableEntryName(name: string): boolean;
+/**
+ * Whether a ROOT key can serve as half of a node id. This is what ENFORCES the invariant `nodeId`
+ * documents: a key containing the NUL separator would make `splitNodeId` return a different pair
+ * than went in (`"a\0b"` + `""` splits back to `"a"` + `"b\0"`), silently corrupting the identity
+ * that `dirs` / `marks` are keyed by. Root keys are caller-supplied and generic, so the component
+ * checks rather than assumes.
+ */
+export declare function isUsableRootKey(key: string): boolean;
+/** The indent class for a depth. */
+export declare function indentClass(depth: number): string;
+/** A directory row's class. */
+export declare function dirRowClass(kind: "mount" | "repo" | "dir", depth: number, selected?: boolean): string;
+/** A file row's class. */
+export declare function fileRowClass(depth: number, selected: boolean): string;
+export interface FileTreeDirRow {
+    type: "dir";
+    id: string;
+    rootKey: string;
+    relPath: string;
+    name: string;
+    depth: number;
+    kind: "mount" | "repo" | "dir";
+    open: boolean;
+    chevron: string;
+    glyph: string;
+    badges: FileRowBadge[];
+    className: string;
+}
+export interface FileTreeFileRow {
+    type: "file";
+    id: string;
+    rootKey: string;
+    relPath: string;
+    name: string;
+    depth: number;
+    glyph: string;
+    mark: GitMark | null;
+    selected: boolean;
+    className: string;
+}
+export interface FileTreeNoteRow {
+    type: "note";
+    id: string;
+    depth: number;
+    /** `unavailable` / `empty` are two of the four honest states; `loading` / `truncated` are the
+     *  tree's other two informational rows. */
+    status: "loading" | "truncated" | HonestStatus;
+    text: string;
+    className: string;
+}
+export type FileTreeRow = FileTreeDirRow | FileTreeFileRow | FileTreeNoteRow;
+export interface DeriveFileTreeInput {
+    mode: FileTreeMode;
+    roots: readonly FileTreeRootSpec[];
+    /** Every known directory listing, keyed by `nodeId(rootKey, relPath)`. A root's own listing is
+     *  keyed with `relPath: ""`. A key that is absent reads as "not fetched yet". */
+    dirs: Readonly<Record<string, DirState>>;
+    /** The node ids currently expanded. */
+    expanded: ReadonlySet<string>;
+    /** The previewed FILE's node id, if any. */
+    selectedId?: string | null;
+    /** Git marks keyed by `nodeId(rootKey, relPath)`. Absent = NO mark (never a fabricated clean). */
+    marks?: Readonly<Record<string, GitMark>>;
+}
+/**
+ * Flatten the tree into the ordered rows the bindings render. Depth-first, roots in the order given;
+ * a closed node contributes only its own row.
+ *
+ * Every non-entry outcome becomes an explicit NOTE row rather than silence:
+ *   · a listing still in flight        ⇒ `loading`
+ *   · a listing that could not be read ⇒ `unavailable`   (honest state)
+ *   · a listing that is genuinely empty⇒ `empty`         (honest state)
+ *   · a listing the source capped      ⇒ `truncated`
+ * An expanded node with NO cache entry at all is `loading`, because "the caller has not fetched it
+ * yet" is exactly that and must never read as empty.
+ *
+ * Marks are applied only where the caller supplied one for that exact path — an absent mark renders
+ * no glyph, never a fabricated "clean". Pure: no fetching, no caching, no policy about WHEN a
+ * listing should be loaded (that is the product's lazy-expansion concern).
+ */
+export declare function deriveFileTreeRows(input: DeriveFileTreeInput): FileTreeRow[];
+/** The number of FILE rows actually rendered — the rail header's default count, and the only one
+ *  that is provably equal to what the operator can see. Pure. */
+export declare function countFileRows(rows: readonly FileTreeRow[]): number;
+/**
+ * Total FILE entries DISCOVERED across every cached listing — a different number from
+ * `countFileRows`, and deliberately so.
+ *
+ * This counts what the caller has listed so far ANYWHERE in its cache, including directories that
+ * are currently collapsed or no longer reachable from the active roots. It is therefore NOT the
+ * count of visible rows and must not be presented as one: a collapsed `docs/` whose listing is
+ * cached still contributes its files here while rendering none. `FileTree` defaults its header to
+ * `countFileRows` for exactly that reason; pass this explicitly as `count` only when "files
+ * discovered so far" is the number you actually mean.
+ *
+ * Malformed and duplicate names are excluded on the same tests the walk applies, and `Object.keys`
+ * is own-enumerable only, matching the walk's own-key guard. Pure.
+ */
+export declare function countLoadedFiles(dirs: Readonly<Record<string, DirState>>): number;
+/** One option in the rail's scope picker. `count` is the option's root count (the card's right-hand
+ *  number). `dividerAfter` draws the card's 1px rule — the caller decides where the grouping falls
+ *  rather than this module guessing a vocabulary of scope keys it does not own. */
+export interface FileScopeOption {
+    key: string;
+    label: string;
+    count: number;
+    dividerAfter?: boolean;
+}
+export declare function scopeItemClass(active: boolean): string;