@leavepulse/ui 0.12.0

package/src/index.ts

@@ -0,0 +1,146 @@
+export { default as LayoutCanvas } from "./components/LayoutCanvas.vue"
+export { default as LpAlert } from "./components/LpAlert.vue"
+export { default as LpAppShell } from "./components/LpAppShell.vue"
+export { default as LpAutocomplete } from "./components/LpAutocomplete.vue"
+export type { AutocompleteOption } from "./components/LpAutocomplete.vue"
+export { default as LpAvatar } from "./components/LpAvatar.vue"
+export { default as LpBadge } from "./components/LpBadge.vue"
+export { default as LpBreadcrumbs } from "./components/LpBreadcrumbs.vue"
+export type { Crumb } from "./components/LpBreadcrumbs.vue"
+export { default as LpButton } from "./components/LpButton.vue"
+export { default as LpCalendar } from "./components/LpCalendar.vue"
+export { default as LpCard } from "./components/LpCard.vue"
+export { default as LpCheckbox } from "./components/LpCheckbox.vue"
+export { default as LpCodeBlock } from "./components/LpCodeBlock.vue"
+export type { CodeLang } from "./components/codeHighlight"
+export { default as LpCommandPalette } from "./components/LpCommandPalette.vue"
+export type { Command } from "./components/LpCommandPalette.vue"
+export { default as LpConfirmDialog } from "./components/LpConfirmDialog.vue"
+export { default as LpContextMenu } from "./components/LpContextMenu.vue"
+export type { ContextMenuItemDef } from "./components/LpContextMenu.vue"
+export { default as LpDatePicker } from "./components/LpDatePicker.vue"
+export { default as LpDisclosure } from "./components/LpDisclosure.vue"
+export { default as LpDivider } from "./components/LpDivider.vue"
+export { default as LpDrawer } from "./components/LpDrawer.vue"
+export { default as LpDropdownMenu } from "./components/LpDropdownMenu.vue"
+export type { MenuItem } from "./components/LpDropdownMenu.vue"
+export { default as LpEmptyState } from "./components/LpEmptyState.vue"
+export { default as LpFormField } from "./components/LpFormField.vue"
+export { default as LpIcon } from "./components/LpIcon.vue"
+export { default as LpInfraNode } from "./components/LpInfraNode.vue"
+export type { InfraNodeData } from "./components/LpInfraNode.vue"
+export { default as LpInput } from "./components/LpInput.vue"
+export { default as LpLink } from "./components/LpLink.vue"
+export { default as LpLogViewer } from "./components/LpLogViewer.vue"
+export type { LogLevel, LogLine } from "./components/LpLogViewer.vue"
+export { default as LpModal } from "./components/LpModal.vue"
+export { default as LpNotificationBell } from "./components/LpNotificationBell.vue"
+export type { NotificationItem } from "./components/LpNotificationBell.vue"
+export { default as LpNumberField } from "./components/LpNumberField.vue"
+export { default as LpOtpInput } from "./components/LpOtpInput.vue"
+export { default as LpPagination } from "./components/LpPagination.vue"
+export { default as LpPasswordInput } from "./components/LpPasswordInput.vue"
+export { default as LpPhoneInput } from "./components/LpPhoneInput.vue"
+export type { PhoneDetail } from "./components/LpPhoneInput.vue"
+export { flagEmoji, loadCountries, matchCountryByValue } from "./components/countries"
+export type { Country } from "./components/countries"
+export { default as LpPopover } from "./components/LpPopover.vue"
+export { default as LpProgress } from "./components/LpProgress.vue"
+export { default as LpRadio } from "./components/LpRadio.vue"
+export { default as LpRadioGroup } from "./components/LpRadioGroup.vue"
+export type { RadioOption } from "./components/LpRadioGroup.vue"
+export { default as LpScrollArea } from "./components/LpScrollArea.vue"
+export { default as LpSegmented } from "./components/LpSegmented.vue"
+export type { SegmentedOption } from "./components/LpSegmented.vue"
+export { default as LpSelect } from "./components/LpSelect.vue"
+export type { SelectOption, SelectValue } from "./components/LpSelect.vue"
+export { default as LpServiceNode } from "./components/LpServiceNode.vue"
+export type { ServiceNodeData } from "./components/LpServiceNode.vue"
+export { default as LpSidebar } from "./components/LpSidebar.vue"
+export type { SidebarItem, SidebarSection } from "./components/LpSidebar.vue"
+export { default as LpSkeleton } from "./components/LpSkeleton.vue"
+export { default as LpSlider } from "./components/LpSlider.vue"
+export { default as LpStat } from "./components/LpStat.vue"
+export { default as LpStepper } from "./components/LpStepper.vue"
+export type { Step } from "./components/LpStepper.vue"
+export { default as LpSwitch } from "./components/LpSwitch.vue"
+export { default as LpTable } from "./components/LpTable.vue"
+export type { SortState, TableColumn } from "./components/LpTable.vue"
+export { default as LpTableOfContents } from "./components/LpTableOfContents.vue"
+export type { TocLink } from "./components/LpTableOfContents.vue"
+export { default as LpTabs } from "./components/LpTabs.vue"
+export type { TabItem } from "./components/LpTabs.vue"
+export { default as LpTextarea } from "./components/LpTextarea.vue"
+export { default as LpThemeSwitcher } from "./components/LpThemeSwitcher.vue"
+export { default as LpToaster } from "./components/LpToaster.vue"
+export { default as LpTooltip } from "./components/LpTooltip.vue"
+export { default as LpTopologyCanvas } from "./components/LpTopologyCanvas.vue"
+export type {
+  CanvasViewport,
+  EdgeCategory,
+  EdgeObserved,
+  TopologyEdge,
+  TopologyLane,
+  TopologyNode,
+} from "./components/LpTopologyCanvas.vue"
+export { default as LpUptimeBar } from "./components/LpUptimeBar.vue"
+export type { UptimeSegment, UptimeStatus } from "./components/LpUptimeBar.vue"
+
+export {
+  addLeaf,
+  addTab,
+  countBlocks,
+  countLeaves,
+  deserializeLayout,
+  makeLayout,
+  moveLeaf,
+  removeBlock,
+  removeLeaf,
+  reorderTab,
+  resizeAt,
+  setActiveTab,
+  serializeLayout,
+} from "./layout/tree"
+export type { Dir, LayoutNode, Leaf, Side, Split } from "./layout/tree"
+export { blockTitle, defineBlocks } from "./layout/registry"
+export type { BlockDef, BlockRegistry } from "./layout/registry"
+export { useLayout } from "./layout/useLayout"
+export type { UseLayout, UseLayoutOptions } from "./layout/useLayout"
+
+// theme engine — themes are JSON (TokenSet), applied at runtime
+export {
+  applyTheme,
+  applyThemeWithTransition,
+  bootstrapTheme,
+  parseTheme,
+  serializeTheme,
+  themeToCssRule,
+  themeToCssVars,
+  useTheme,
+} from "./theme/useTheme"
+export type { RevealOrigin } from "./theme/useTheme"
+export { DEFAULT_SURFACE } from "./theme/tokens"
+export { defineTheme } from "./theme/define"
+export type { ThemeOverrides } from "./theme/define"
+export type {
+  ColorTokens,
+  DensityTokens,
+  FontTokens,
+  ShapeTokens,
+  SurfaceTokens,
+  TokenSet,
+} from "./theme/tokens"
+export { amber, dark, leavepulse, light, lime, nord, presets, rose, violet } from "./theme/presets"
+export type { PresetName } from "./theme/presets"
+export { parseConfig, serializeConfig, UI_CONFIG_VERSION } from "./theme/config"
+export type { UiConfig } from "./theme/config"
+
+export { useInputFilter } from "./composables/useInputFilter"
+export type { UseInputFilterOptions } from "./composables/useInputFilter"
+export { useToast } from "./composables/useToast"
+export type {
+  ToastAction,
+  ToastItem,
+  ToastOptions,
+  ToastVariant,
+} from "./composables/useToast"

package/src/layout/registry.ts

@@ -0,0 +1,44 @@
+import type { Component } from "vue"
+
+/*
+ * Block registry — the consumer's catalogue of what a layout cell can hold.
+ *
+ * The layout tree stores only block ids (plain strings, serializable). The
+ * registry maps each id to how it should render and chrome: the component, a
+ * human title for the tab/header, an optional icon, and whether the user may
+ * close it. LayoutCanvas reads this so it can draw tab bars + headers itself —
+ * the consumer supplies the catalogue, not per-cell wiring.
+ */
+
+export interface BlockDef {
+  /**
+   * Content component for this block. Optional: when the consumer renders block
+   * content via the canvas's #block slot (keyed by id), the registry is used
+   * only for tab chrome (title/icon) and no component is needed here.
+   */
+  component?: Component
+  /** Human label shown on the tab / cell header. Defaults to the id. */
+  title?: string
+  /** Optional iconify name (e.g. "lucide:activity") for the tab. */
+  icon?: string
+  /** Whether the user may close this block. Defaults to true. */
+  closable?: boolean
+  /** Props passed to the component. */
+  props?: Record<string, unknown>
+}
+
+export type BlockRegistry = Record<string, BlockDef>
+
+/**
+ * Identity helper that pins the key type so callers get autocomplete on block
+ * ids elsewhere (e.g. when seeding a layout). Purely for inference — it returns
+ * the object unchanged.
+ */
+export function defineBlocks<const T extends BlockRegistry>(blocks: T): T {
+  return blocks
+}
+
+/** Resolve a block's display title, falling back to its id. */
+export function blockTitle(registry: BlockRegistry, id: string): string {
+  return registry[id]?.title ?? id
+}

package/src/layout/tree.ts

@@ -0,0 +1,288 @@
+import { reactive } from "vue"
+
+/*
+ * Layout tree model for LayoutCanvas.
+ *
+ * A layout is a tree of splits (row/col containers) and leaves (blocks).
+ * Sizes are flex fractions among siblings, so the layout is resolution-
+ * independent and serializes cleanly to JSON (persist to disk / config).
+ */
+
+export type Dir = "row" | "col"
+export type Side = "left" | "right" | "top" | "bottom" | "center"
+
+export interface Leaf {
+  kind: "leaf"
+  id: string
+  /**
+   * Block ids stacked as tabs in this cell. A plain cell is a single-element
+   * stack; dropping onto a cell's center adds another tab. The consumer maps
+   * each id to content via the canvas slot.
+   */
+  blocks: string[]
+  /** Index into `blocks` of the visible tab. */
+  active: number
+  /** Flex fraction among siblings. */
+  size: number
+}
+export interface Split {
+  kind: "split"
+  id: string
+  dir: Dir
+  size: number
+  children: LayoutNode[]
+}
+export type LayoutNode = Leaf | Split
+
+let uid = 0
+const nid = () => `lp-n${uid++}`
+
+function leaf(block: string): Leaf {
+  return { kind: "leaf", id: nid(), blocks: [block], active: 0, size: 1 }
+}
+
+/** Build a single-row layout from a flat list of block ids (one cell each). */
+export function makeLayout(blocks: string[]): Split {
+  return reactive<Split>({
+    kind: "split",
+    id: nid(),
+    dir: "row",
+    size: 1,
+    children: blocks.map<Leaf>(leaf),
+  })
+}
+
+export function findParent(node: Split, childId: string): Split | null {
+  for (const c of node.children) {
+    if (c.id === childId) return node
+    if (c.kind === "split") {
+      const r = findParent(c, childId)
+      if (r) return r
+    }
+  }
+  return null
+}
+
+export function findLeaf(node: LayoutNode, id: string): Leaf | null {
+  if (node.kind === "leaf") return node.id === id ? node : null
+  for (const c of node.children) {
+    const r = findLeaf(c, id)
+    if (r) return r
+  }
+  return null
+}
+
+export function countLeaves(node: LayoutNode): number {
+  if (node.kind === "leaf") return 1
+  return node.children.reduce((s, c) => s + countLeaves(c), 0)
+}
+
+/** Total blocks across all cells (a tabbed cell counts each of its tabs). */
+export function countBlocks(node: LayoutNode): number {
+  if (node.kind === "leaf") return node.blocks.length
+  return node.children.reduce((s, c) => s + countBlocks(c), 0)
+}
+
+function detach(root: Split, id: string): void {
+  const parent = findParent(root, id)
+  if (!parent) return
+  const idx = parent.children.findIndex((c) => c.id === id)
+  parent.children.splice(idx, 1)
+  collapse(root, parent)
+}
+
+/** A container left with a single child collapses into that child. */
+function collapse(root: Split, parent: Split): void {
+  if (parent === root || parent.children.length !== 1) return
+  const grand = findParent(root, parent.id)
+  if (!grand) return
+  const only = parent.children[0]
+  only.size = parent.size
+  const pIdx = grand.children.findIndex((c) => c.id === parent.id)
+  grand.children.splice(pIdx, 1, only)
+}
+
+/** Remove an entire cell (with all its tabs). */
+export function removeLeaf(root: Split, id: string): void {
+  if (countLeaves(root) <= 1) return // keep at least one cell
+  detach(root, id)
+}
+
+/**
+ * Remove one tab from a cell. Removing the last tab removes the cell itself
+ * (unless it's the only block left in the whole layout, which is kept).
+ */
+export function removeBlock(root: Split, leafId: string, index: number): void {
+  const target = findLeaf(root, leafId)
+  if (!target || index < 0 || index >= target.blocks.length) return
+  if (target.blocks.length > 1) {
+    target.blocks.splice(index, 1)
+    if (target.active >= target.blocks.length) target.active = target.blocks.length - 1
+    return
+  }
+  // Last tab in this cell → drop the cell, but never empty the whole layout.
+  if (countBlocks(root) <= 1) return
+  detach(root, leafId)
+}
+
+export function addLeaf(root: Split, block: string, side: Side = "right"): void {
+  const targetId = root.children[root.children.length - 1]?.id
+  if (!targetId) {
+    root.children.push(leaf(block))
+    return
+  }
+  if (side === "center") {
+    addTab(root, targetId, block)
+    return
+  }
+  insertBeside(root, leaf(block), targetId, side)
+}
+
+/** Append a block as a new tab in the target cell and focus it. */
+export function addTab(root: Split, leafId: string, block: string): void {
+  const target = findLeaf(root, leafId)
+  if (!target) return
+  target.blocks.push(block)
+  target.active = target.blocks.length - 1
+}
+
+/** Switch the visible tab of a cell. */
+export function setActiveTab(root: Split, leafId: string, index: number): void {
+  const target = findLeaf(root, leafId)
+  if (!target || index < 0 || index >= target.blocks.length) return
+  target.active = index
+}
+
+/**
+ * Reorder a tab within its cell, moving the block at `from` to `to`. The same
+ * block stays visible afterwards (active follows the moved block by identity,
+ * not by index). Always available — not gated by edit mode.
+ */
+export function reorderTab(root: Split, leafId: string, from: number, to: number): void {
+  const target = findLeaf(root, leafId)
+  if (!target) return
+  const n = target.blocks.length
+  if (from < 0 || from >= n || to < 0 || to >= n || from === to) return
+  const activeBlock = target.blocks[target.active]
+  const [moved] = target.blocks.splice(from, 1)
+  target.blocks.splice(to, 0, moved)
+  target.active = target.blocks.indexOf(activeBlock)
+}
+
+function insertBeside(
+  root: Split,
+  moving: Leaf,
+  targetId: string,
+  side: Side,
+): void {
+  const parent = findParent(root, targetId)
+  if (!parent) return
+  const idx = parent.children.findIndex((c) => c.id === targetId)
+  const target = parent.children[idx]
+
+  const wantDir: Dir = side === "left" || side === "right" ? "row" : "col"
+  const before = side === "left" || side === "top"
+
+  if (parent.dir === wantDir) {
+    moving.size = target.size / 2
+    target.size = target.size / 2
+    parent.children.splice(before ? idx : idx + 1, 0, moving)
+  } else {
+    const wrap: Split = {
+      kind: "split",
+      id: nid(),
+      dir: wantDir,
+      size: target.size,
+      children: before
+        ? [{ ...moving, size: 1 }, { ...target, size: 1 }]
+        : [{ ...target, size: 1 }, { ...moving, size: 1 }],
+    }
+    parent.children.splice(idx, 1, wrap)
+  }
+}
+
+/**
+ * Move an existing cell to a target. An edge side splits beside the target;
+ * `center` merges the moving cell's tabs into the target cell (and focuses
+ * the first moved tab).
+ */
+export function moveLeaf(
+  root: Split,
+  movingId: string,
+  targetId: string,
+  side: Side,
+): void {
+  if (movingId === targetId) return
+  const moving = findLeaf(root, movingId)
+  if (!moving) return
+
+  if (side === "center") {
+    const target = findLeaf(root, targetId)
+    if (!target) return
+    const merged = moving.blocks
+    detach(root, movingId)
+    target.active = target.blocks.length
+    target.blocks.push(...merged)
+    return
+  }
+
+  detach(root, movingId)
+  moving.size = 1
+  insertBeside(root, moving, targetId, side)
+}
+
+/** Splitter drag: redistribute size between two adjacent siblings. */
+export function resizeAt(parent: Split, index: number, deltaFraction: number): void {
+  const a = parent.children[index]
+  const b = parent.children[index + 1]
+  if (!a || !b) return
+  const total = a.size + b.size
+  const min = total * 0.12
+  const na = Math.max(min, Math.min(total - min, a.size + deltaFraction * total))
+  a.size = na
+  b.size = total - na
+}
+
+// ── serialization ────────────────────────────────────────────
+interface SerializedLeaf {
+  kind: "leaf"
+  blocks: string[]
+  active: number
+  size: number
+  /** Legacy single-block form (pre-tabs); hydrated into `blocks`. */
+  block?: string
+}
+interface SerializedSplit {
+  kind: "split"
+  dir: Dir
+  size: number
+  children: SerializedNode[]
+}
+type SerializedNode = SerializedLeaf | SerializedSplit
+
+export function serializeLayout(root: Split): SerializedNode {
+  const strip = (n: LayoutNode): SerializedNode =>
+    n.kind === "leaf"
+      ? { kind: "leaf", blocks: [...n.blocks], active: n.active, size: n.size }
+      : { kind: "split", dir: n.dir, size: n.size, children: n.children.map(strip) }
+  return strip(root) as SerializedSplit
+}
+
+export function deserializeLayout(data: SerializedNode): Split {
+  const hydrate = (n: SerializedNode): LayoutNode => {
+    if (n.kind === "leaf") {
+      // Accept both the tabbed form and the legacy single-`block` form.
+      const blocks = n.blocks ?? (n.block != null ? [n.block] : [])
+      const active = Math.min(Math.max(n.active ?? 0, 0), Math.max(blocks.length - 1, 0))
+      return { kind: "leaf", id: nid(), blocks, active, size: n.size ?? 1 }
+    }
+    return {
+      kind: "split",
+      id: nid(),
+      dir: n.dir,
+      size: n.size ?? 1,
+      children: n.children.map(hydrate),
+    }
+  }
+  return reactive(hydrate(data) as Split)
+}

package/src/layout/useLayout.ts

@@ -0,0 +1,134 @@
+import { computed, ref, shallowRef, type Ref } from "vue"
+import {
+  addLeaf,
+  addTab,
+  countBlocks,
+  deserializeLayout,
+  makeLayout,
+  moveLeaf,
+  removeBlock,
+  removeLeaf,
+  reorderTab,
+  resizeAt,
+  setActiveTab,
+  serializeLayout,
+  type Side,
+  type Split,
+} from "./tree"
+
+/*
+ * useLayout — stateful controller around the layout tree.
+ *
+ * tree.ts is a pile of pure-ish mutators; this composable is the ergonomic
+ * surface a consumer actually wires to UI: it owns the reactive tree, snapshots
+ * every structural edit for undo/redo, and exposes save/load/reset against a
+ * serialized form. The canvas calls the same mutators for drag/drop/resize, so
+ * those go through `record()` too and land in history.
+ *
+ * History holds serialized snapshots (plain JSON), not live trees, so an undo
+ * can't smuggle stale reactive nodes back in.
+ */
+
+export interface UseLayoutOptions {
+  /** Initial block ids, left-to-right, when no saved layout is loaded. */
+  initial: string[]
+  /** Max undo depth. */
+  historyLimit?: number
+}
+
+export interface UseLayout {
+  /** The live reactive tree to hand to <LayoutCanvas v-model>. */
+  layout: Ref<Split>
+  /** Block count across all tabs, handy for "N blocks" labels and guards. */
+  count: Ref<number>
+  canUndo: Ref<boolean>
+  canRedo: Ref<boolean>
+  /** Add a block: a new cell on an edge, or a tab on the last cell (center). */
+  add: (block: string, side?: Side) => void
+  /** Add a block as a tab in a specific cell. */
+  addTab: (leafId: string, block: string) => void
+  /** Switch the visible tab of a cell. */
+  setActive: (leafId: string, index: number) => void
+  /** Reorder a tab within its cell (always available, not edit-gated). */
+  reorderTab: (leafId: string, from: number, to: number) => void
+  /** Remove one tab (drops the cell when it was the last tab). */
+  removeBlock: (leafId: string, index: number) => void
+  /** Remove an entire cell with all its tabs. */
+  remove: (leafId: string) => void
+  move: (movingId: string, targetId: string, side: Side) => void
+  resize: (parent: Split, index: number, deltaFraction: number) => void
+  undo: () => void
+  redo: () => void
+  /** Replace the whole layout from a flat block list. */
+  reset: (blocks?: string[]) => void
+  /** Serialize to JSON-safe data for persistence. */
+  serialize: () => unknown
+  /** Replace the layout from previously serialized data. */
+  hydrate: (data: unknown) => void
+}
+
+export function useLayout(options: UseLayoutOptions): UseLayout {
+  const limit = options.historyLimit ?? 50
+  const layout = shallowRef<Split>(makeLayout(options.initial))
+  const count = computed(() => countBlocks(layout.value))
+
+  const past = ref<string[]>([])
+  const future = ref<string[]>([])
+  const canUndo = computed(() => past.value.length > 0)
+  const canRedo = computed(() => future.value.length > 0)
+
+  const snapshot = () => JSON.stringify(serializeLayout(layout.value))
+
+  // Capture the pre-edit state, run the structural change, drop any redo branch.
+  function record(mutate: () => void) {
+    const before = snapshot()
+    mutate()
+    past.value.push(before)
+    if (past.value.length > limit) past.value.shift()
+    future.value = []
+  }
+
+  function restore(serialized: string) {
+    layout.value = deserializeLayout(JSON.parse(serialized))
+  }
+
+  return {
+    layout,
+    count,
+    canUndo,
+    canRedo,
+    add: (block, side) => record(() => addLeaf(layout.value, block, side)),
+    addTab: (leafId, block) => record(() => addTab(layout.value, leafId, block)),
+    setActive: (leafId, index) => setActiveTab(layout.value, leafId, index),
+    reorderTab: (leafId, from, to) => record(() => reorderTab(layout.value, leafId, from, to)),
+    removeBlock: (leafId, index) => record(() => removeBlock(layout.value, leafId, index)),
+    remove: (leafId) => record(() => removeLeaf(layout.value, leafId)),
+    move: (movingId, targetId, side) =>
+      record(() => moveLeaf(layout.value, movingId, targetId, side)),
+    // Resize fires continuously during a divider drag; recording every frame
+    // would flood history, so it mutates without a snapshot. (A consumer that
+    // wants resize in history can wrap a single record() around the gesture.)
+    resize: (parent, index, delta) => resizeAt(parent, index, delta),
+    undo: () => {
+      const prev = past.value.pop()
+      if (prev === undefined) return
+      future.value.push(snapshot())
+      restore(prev)
+    },
+    redo: () => {
+      const next = future.value.pop()
+      if (next === undefined) return
+      past.value.push(snapshot())
+      restore(next)
+    },
+    reset: (blocks) =>
+      record(() => {
+        layout.value = makeLayout(blocks ?? options.initial)
+      }),
+    serialize: () => serializeLayout(layout.value),
+    hydrate: (data) =>
+      record(() => {
+        layout.value = deserializeLayout(data as Parameters<typeof deserializeLayout>[0])
+      }),
+  }
+}

package/src/nuxt.ts

@@ -0,0 +1,22 @@
+/*
+ * Nuxt module — auto-registers every kit component globally so consuming apps
+ * use <LpButton> / <LpThemeSwitcher> / … with no per-app component list to
+ * maintain. Add it to a Nuxt app's `modules`:
+ *
+ *   export default defineNuxtConfig({ modules: ["@leavepulse/ui/nuxt"] })
+ *
+ * The list comes from the generated component-names file (kept in sync with the
+ * actual components at build), so a NEW component is available everywhere with
+ * no consumer change.
+ */
+import { addComponent, defineNuxtModule } from "@nuxt/kit"
+import { COMPONENT_NAMES } from "./component-names"
+
+export default defineNuxtModule({
+  meta: { name: "@leavepulse/ui", configKey: "leavepulseUi" },
+  setup() {
+    for (const name of COMPONENT_NAMES) {
+      addComponent({ name, export: name, filePath: "@leavepulse/ui" })
+    }
+  },
+})

package/src/theme/config.ts

@@ -0,0 +1,48 @@
+/*
+ * UiConfig — the canonical, complete UI-state snapshot for a LeavePulse app.
+ *
+ * Deliberately broader than the launcher's old theme config: it carries the
+ * THEME *and* the LAYOUT (block placement) in one serializable object, plus a
+ * schema version for forward migration. This is the source of truth apps load
+ * from / save to disk.
+ */
+import type { Split } from "../layout/tree"
+import { serializeLayout, deserializeLayout } from "../layout/tree"
+import type { TokenSet } from "./tokens"
+import { parseTheme, serializeTheme } from "./useTheme"
+
+export const UI_CONFIG_VERSION = 1
+
+export interface UiConfig {
+  version: number
+  theme: TokenSet
+  /** Optional — apps without a composable layout omit it. */
+  layout?: Split
+}
+
+export interface SerializedUiConfig {
+  version: number
+  theme: TokenSet
+  layout?: unknown
+}
+
+export function serializeConfig(config: UiConfig): string {
+  const out: SerializedUiConfig = {
+    version: UI_CONFIG_VERSION,
+    theme: JSON.parse(serializeTheme(config.theme)),
+    layout: config.layout ? serializeLayout(config.layout) : undefined,
+  }
+  return JSON.stringify(out)
+}
+
+export function parseConfig(json: string): UiConfig {
+  const raw = JSON.parse(json) as SerializedUiConfig
+  if (!raw || typeof raw !== "object") throw new Error("Invalid UiConfig")
+  return {
+    version: raw.version ?? UI_CONFIG_VERSION,
+    theme: parseTheme(JSON.stringify(raw.theme)),
+    layout: raw.layout
+      ? deserializeLayout(raw.layout as Parameters<typeof deserializeLayout>[0])
+      : undefined,
+  }
+}