refactor!: keep lib helpers out of the public surface

CHANGELOG.md

@@ -59,6 +59,16 @@ contract — modules that are not exported are internal and may change in any re
   `ThemeProvider` writes `.light` for resolved-light mode, so hosts on the provider need
   no change.
 
+- **Five helper modules are internal.** `lib/csv`, `lib/url`, `lib/utils` (`cn`),
+  `lib/workflow-registry` and `ui/chat-dock-timing` leave the root barrel and the
+  `exports` map, taking with them `cn`, `parseCsv` and the CSV caps, `isSafeUrl` /
+  `toSafeHref`, the `CHAT_DOCK_*` timings, and the workflow status and scope tables
+  (`WORKFLOW_STATUS_*`, `WORKFLOW_SCOPE_BADGE_TONE`, `LIVE_RUN_PHASE_*`,
+  `GATE_KIND_LABEL`, `workflowStatusLive`, `workflowScopeLabel`) with their types.
+  `StepListItem` and `StepDisplayStatus` stay public from `ui/step-list`;
+  `GateShellModel` and `GateKind` from `ui/gate-block`. For `cn`, compose `clsx` and
+  `tailwind-merge` directly: `twMerge(clsx(...inputs))`.
+
 ### Added
 
 - **`ui/shimmer-text` and `ui/thinking-label`** — a token-pure shimmer sweep

package.json

@@ -143,10 +143,6 @@
       "types": "./dist/lib/chat-parts.d.ts",
       "default": "./dist/lib/chat-parts.js"
     },
-    "./lib/csv": {
-      "types": "./dist/lib/csv.d.ts",
-      "default": "./dist/lib/csv.js"
-    },
     "./lib/metrics": {
       "types": "./dist/lib/metrics.d.ts",
       "default": "./dist/lib/metrics.js"
@@ -163,22 +159,10 @@
       "types": "./dist/lib/theme.d.ts",
       "default": "./dist/lib/theme.js"
     },
-    "./lib/url": {
-      "types": "./dist/lib/url.d.ts",
-      "default": "./dist/lib/url.js"
-    },
-    "./lib/utils": {
-      "types": "./dist/lib/utils.d.ts",
-      "default": "./dist/lib/utils.js"
-    },
     "./lib/workflow-display-flow": {
       "types": "./dist/lib/workflow-display-flow.d.ts",
       "default": "./dist/lib/workflow-display-flow.js"
     },
-    "./lib/workflow-registry": {
-      "types": "./dist/lib/workflow-registry.d.ts",
-      "default": "./dist/lib/workflow-registry.js"
-    },
     "./lib/workflow-run": {
       "types": "./dist/lib/workflow-run.d.ts",
       "default": "./dist/lib/workflow-run.js"
@@ -255,10 +239,6 @@
       "types": "./dist/ui/chat-composer.d.ts",
       "default": "./dist/ui/chat-composer.js"
     },
-    "./ui/chat-dock-timing": {
-      "types": "./dist/ui/chat-dock-timing.d.ts",
-      "default": "./dist/ui/chat-dock-timing.js"
-    },
     "./ui/chat-input": {
       "types": "./dist/ui/chat-input.d.ts",
       "default": "./dist/ui/chat-input.js"

scripts/generate-exports.mjs

@@ -22,7 +22,14 @@ import { join, relative } from "node:path";
 const ROOT = new URL("..", import.meta.url).pathname;
 const SRC = join(ROOT, "src");
 
-const INTERNAL = new Set(["lib/chart-geometry"]);
+const INTERNAL = new Set([
+  "lib/chart-geometry",
+  "lib/csv",
+  "lib/url",
+  "lib/utils",
+  "lib/workflow-registry",
+  "ui/chat-dock-timing",
+]);
 const BARREL_EXCLUDED = new Set();
 
 const walk = (dir) =>

src/index.ts

@@ -21,15 +21,11 @@ export * from "./lib/artifact.js";
 export * from "./lib/chart-palette.js";
 export * from "./lib/chat-message.js";
 export * from "./lib/chat-parts.js";
-export * from "./lib/csv.js";
 export * from "./lib/metrics.js";
 export * from "./lib/now-item.js";
 export * from "./lib/relative-time.js";
 export * from "./lib/theme.js";
-export * from "./lib/url.js";
-export * from "./lib/utils.js";
 export * from "./lib/workflow-display-flow.js";
-export * from "./lib/workflow-registry.js";
 export * from "./lib/workflow-run.js";
 export * from "./lib/workflow-run-error.js";
 export * from "./lib/workflow-run-progress.js";
@@ -49,7 +45,6 @@ export * from "./ui/card.js";
 export * from "./ui/category-bars.js";
 export * from "./ui/chart-frame.js";
 export * from "./ui/chat-composer.js";
-export * from "./ui/chat-dock-timing.js";
 export * from "./ui/chat-input.js";
 export * from "./ui/chat-panel.js";
 export * from "./ui/chat-thread.js";

src/lib/workflow-registry.ts

@@ -64,50 +64,6 @@ export const WORKFLOW_SCOPE_BADGE_TONE: Record<WorkflowScope, BadgeTone> = {
   personal: "accent",
 };
 
-/** A live run's phase as an inspector or list row reports it — a coarser
- * vocabulary than `RunStatus` in `workflow-run.ts` (no `provisioning`), for
- * surfaces that only distinguish what a reader can act on. */
-export type LiveRunPhase = "running" | "awaiting" | "completed" | "failed" | "cancelled";
-
-export const LIVE_RUN_PHASE_TONE: Record<LiveRunPhase, WorkflowStatusTone> = {
-  running: "running",
-  awaiting: "awaiting",
-  completed: "done",
-  failed: "fail",
-  cancelled: "fail",
-};
-
-export const LIVE_RUN_PHASE_LABEL: Record<LiveRunPhase, string> = {
-  running: "Running",
-  awaiting: "Needs you",
-  completed: "Done",
-  failed: "Failed",
-  cancelled: "Cancelled",
-};
-
-export type WorkflowListItemKind = "run" | "schedule";
-
-/** One dense row in the combined live-runs-and-schedules list. */
-export type WorkflowListItem = {
-  readonly id: string;
-  readonly itemKind: WorkflowListItemKind;
-  /** Primary label — the workflow's kind, already humanised. */
-  readonly title: string;
-  /** Secondary line under the title: an alias, an origin tag. */
-  readonly subtitle?: string;
-  /** The "when" column: origin phrase for a run, cadence for a schedule. */
-  readonly when: string;
-  readonly scope: WorkflowScope;
-  readonly statusTone: WorkflowStatusTone;
-  readonly statusLabel: string;
-  /** Next-fire or elapsed text, already formatted by the caller. */
-  readonly nextOrElapsed: string;
-  /** Highlights `nextOrElapsed` — the next fire is close, or the run is fresh. */
-  readonly nextSoon?: boolean;
-  /** A live run parked on a human decision gets a subtle accent stripe. */
-  readonly needsYou?: boolean;
-};
-
 export type GateKind = "reviewList" | "choice" | "form" | "multiSelect";
 
 export const GATE_KIND_LABEL: Record<GateKind, string> = {
@@ -124,21 +80,6 @@ export type GateShellModel = {
   readonly prompt?: string;
 };
 
-/** One offering in a workflow-kind picker (distinct from `WorkflowOffering` in
- * `workflow-catalog.tsx`, which drives the run-once grid): this shape adds
- * category grouping and an "already on" badge for a picker that lists kinds
- * to attach to a schedule or an automation rather than to run once. */
-export type KindPickerItem = {
-  readonly id: string;
-  readonly label: string;
-  readonly description: string;
-  /** Grouping key. Omit when every item shares one category. */
-  readonly category?: string;
-  readonly categoryLabel?: string;
-  readonly alreadyOn?: boolean;
-  readonly alreadyOnLabel?: string;
-};
-
 export type StepDisplayStatus = "pending" | "active" | "done" | "failed";
 
 /** One step row in the live inspector's step list. */

src/ui/gate-block.tsx

@@ -3,6 +3,8 @@ import type { ReactNode } from "react";
 import { GATE_KIND_LABEL, type GateShellModel } from "../lib/workflow-registry.js";
 import { cn } from "../lib/utils.js";
 
+export type { GateKind, GateShellModel } from "../lib/workflow-registry.js";
+
 export type GateBlockProps = {
   readonly gate: GateShellModel;
   /** The interactive payload — a review list, choice buttons, a form. */

src/ui/step-list.tsx

@@ -4,6 +4,8 @@ import type { StepDisplayStatus, StepListItem } from "../lib/workflow-registry.j
 import { cn } from "../lib/utils.js";
 import { StatusDot } from "./status-dot.js";
 
+export type { StepDisplayStatus, StepListItem } from "../lib/workflow-registry.js";
+
 const STATE_LABEL: Record<StepDisplayStatus, string> = {
   pending: "Pending",
   active: "Now",

stories/primitives/badge.stories.tsx

@@ -26,8 +26,8 @@ export const Tones = () => (
 const STATUS_TONES: readonly WorkflowStatusTone[] = ["running", "awaiting", "done", "paused", "fail"];
 
 /** A workflow status chip is `Badge` plus a leading `StatusDot` — the tone
- * and pulsing rule come from `lib/workflow-registry`'s mapping tables, not
- * from a dedicated component. */
+ * and pulsing rule come from the internal `lib/workflow-registry` mapping
+ * tables, not from a dedicated component. */
 export const WorkflowStatus = () => (
   <div className="flex flex-wrap items-center gap-2">
     {STATUS_TONES.map((tone) => (
@@ -42,7 +42,7 @@ export const WorkflowStatus = () => (
 const SCOPES: readonly WorkflowScopeValue[] = ["personal", "tenant"];
 
 /** A workflow scope pill is a plain tone lookup on `Badge` — see
- * `WORKFLOW_SCOPE_BADGE_TONE` in `lib/workflow-registry`. */
+ * `WORKFLOW_SCOPE_BADGE_TONE` in the internal `lib/workflow-registry`. */
 export const WorkflowScope = () => (
   <div className="flex flex-wrap items-center gap-2">
     {SCOPES.map((scope) => (