Packages

Install / import	Version	Role
@atheory-ai/kitsune	0.x	Umbrella install target with root runtime export and explicit app, UI, theme, React, dev, and module subpaths
@atheory-ai/kitsune	0.x	Root runtime export — events, commands, modules, providers, boundaries, diagnostics, metadata normalization
@atheory-ai/kitsune/app	0.x	<kit-shell>, <kit-boundary>, the metadata bridge
@atheory-ai/kitsune/ui	0.x	UI custom elements + the modules that drive them
@atheory-ai/kitsune/theme	0.x	Token-driven CSS, theme switching helpers
@atheory-ai/kitsune/react	0.x	React provider, boundary, and hooks
@atheory-ai/kitsune/dev	0.x	Debug module + diagnostic helpers
@atheory-ai/kitsune/modules/analytics	0.x	Analytics capability module
@atheory-ai/kitsune/modules/audit	0.x	Audit trail capability module
@atheory-ai/kitsune/modules/observability	0.x	Observability capability module
@atheory-ai/kitsune/modules/storage	0.x	Storage capability module
@atheory-ai/kitsune/modules/permissions	0.x	Permission-checking capability module
@atheory-ai/kitsune/modules/flags	0.x	Feature flag capability module
@atheory-ai/kitsune/modules/validation	0.x	Native form validation capability module
@atheory-ai/kitsune/modules/search	0.x	In-memory search capability module
@atheory-ai/kitsune/modules/sync	0.x	Runtime event sync capability module
@atheory-ai/kitsune/modules/command-palette	0.x	Command palette registry capability module

Install @atheory-ai/kitsune for the primary path. The subpaths below are import paths exposed by that package. The underlying modular packages are still published under @atheory-ai for advanced dependency control, and all packages follow ^0.x until the runtime API is committed to v1.

@atheory-ai/kitsune

The umbrella package for applications that want a single install target.

pnpm add @atheory-ai/kitsune

The root export is intentionally server-safe and re-exports the framework-neutral runtime from @atheory-ai/kitsune-core.

import { createKitRuntime } from '@atheory-ai/kitsune'

Browser-only surfaces use explicit subpaths:

import '@atheory-ai/kitsune/app'
import '@atheory-ai/kitsune/ui'
import '@atheory-ai/kitsune/theme/tokens.css'

React and capability modules are also available through subpaths:

import { KitShellProvider } from '@atheory-ai/kitsune/react'
import { storageModule } from '@atheory-ai/kitsune/modules/storage'

Subpaths

• @atheory-ai/kitsune/app
• @atheory-ai/kitsune/ui
• @atheory-ai/kitsune/theme
• @atheory-ai/kitsune/theme/tokens.css
• @atheory-ai/kitsune/react
• @atheory-ai/kitsune/dev
• @atheory-ai/kitsune/modules/storage
• @atheory-ai/kitsune/modules/analytics
• @atheory-ai/kitsune/modules/audit
• @atheory-ai/kitsune/modules/observability
• @atheory-ai/kitsune/modules/permissions
• @atheory-ai/kitsune/modules/flags
• @atheory-ai/kitsune/modules/validation
• @atheory-ai/kitsune/modules/search
• @atheory-ai/kitsune/modules/sync
• @atheory-ai/kitsune/modules/command-palette

Dependencies — all published Kitsune packages. React remains an optional peer for the React subpath.

Root Runtime Export

The framework-neutral runtime.

pnpm add @atheory-ai/kitsune

Exports

• createKitRuntime() → KitRuntime
• defineKitModule(module) → KitModule
• createProviderToken<T>(description) → ProviderToken<T>
• normalizeMetadata(input) → NormalizedMetadata
• Types: KitRuntime, KitModule, KitEvent, KitEventInput, KitCommandInput, CommandResult, KitContext, Entity, BoundaryHandle, BoundaryOptions, ProviderToken, KitDiagnostic, EventHandler, CommandHandler, DiagnosticHandler, Unsubscribe

Dependencies — none. Plain TypeScript.

Runtime API reference →

@atheory-ai/kitsune/app

Custom elements for the application skeleton.

pnpm add @atheory-ai/kitsune

Registers

• <kit-shell> — application root, owns the runtime
• <kit-boundary> — context zone with click delegation
• <kit-route> — route context zone that emits route.changed

Exports

• KitShellElement, KitBoundaryElement, KitRouteElement — the classes
• formDraftModule(options?) — applies loaded draft values into matching form controls
• parseMetadata(element, context) — read DOM metadata
• readDomMetadata(element, context) — raw read without normalization
• Types: RouteContext

Dependencies — @atheory-ai/kitsune, lit.

@atheory-ai/kitsune/ui

Web-native UI components and the modules that activate them.

pnpm add @atheory-ai/kitsune

Registers

• <kit-button> — slot-bearing native button
• <kit-card> — card with header / default / footer slots
• <kit-disclosure> — native details/summary disclosure wrapper
• <kit-dialog> — wrapper around native <dialog>
• <kit-field> — labelled form-field container
• <kit-form> — light-DOM form wrapper with composed submit/reset events
• <kit-input> — form-associated custom input
• <kit-select> — form-associated native select wrapper
• <kit-tabs> — ARIA tablist and tabpanel coordinator
• <kit-table> — semantic table styling wrapper
• <kit-toast-region> — fixed-position toast container with aria-live

Exports

• Element classes: KitButtonElement, KitCardElement, KitDisclosureElement, KitDialogElement, KitFieldElement, KitFormElement, KitInputElement, KitSelectElement, KitTabsElement, KitTableElement, KitToastRegionElement
• Modules: dialogModule(options?), notificationModule(options?)
• Events: KitDisclosureToggleEvent, KitFieldChangedEvent, KitFormSubmitEvent, KitFormResetEvent, KitTabsChangeEvent
• Types: KitDisclosureToggleDetail, KitFieldChangedDetail, KitFormSubmitDetail, KitInputType, KitTabsChangeDetail, Toast, ToastTone, DialogModuleOptions, NotificationModuleOptions

Dependencies — @atheory-ai/kitsune, lit.

Elements → · Modules →

@atheory-ai/kitsune/theme

CSS tokens and theme switching.

pnpm add @atheory-ai/kitsune

Exports

• defaultTheme: KitTheme — the built-in token set
• defineTheme(theme) — type-safe theme constructor
• themeToCss(theme, selector?) — render a theme to a CSS string
• applyTheme(theme, root?) — set custom properties on a root element
• Types: KitTheme, KitThemeTokens

Dependencies — none.

Theme tokens →

@atheory-ai/kitsune/react

React adapter — same runtime, React idioms.

pnpm add @atheory-ai/kitsune react react-dom

Exports

• <KitShellProvider> — wraps a tree, installs modules, creates runtime
• <KitBoundary> — semantic context zone with click delegation
• useKitRuntime(), useKitContext(), useKitEmit(), useKitCommand()
• readReactDomMetadata(element, context) — for advanced cases
• Types: KitShellProviderProps, KitBoundaryProps

Dependencies — @atheory-ai/kitsune, react (peer), react-dom (peer).

React integration →

@atheory-ai/kitsune/dev

Development-time diagnostics.

pnpm add @atheory-ai/kitsune

Exports

• debugModule(options?) → a module that logs every event and diagnostic
• devtoolsModule(options?) → a module that records a runtime timeline for in-app inspection
• defineKitDevtoolsElement(registry?) → registers <kit-devtools>
• bindKitDevtoolsElement(element, runtime) → connects an element to an installed devtools module
• DevtoolsToken → provider token for the devtools service
• consoleInspector(options?) → console-backed inspector module
• diagnosticsRecorder(options?) → bounded diagnostics recorder module
• formatDiagnostic(diagnostic) → string formatter
• Types: DebugModuleOptions, DevtoolsModuleOptions, DevtoolsService, DevtoolsTimelineEntry, KitDevtoolsElement, InspectorOptions, RecorderOptions, DiagnosticsRecorder

Dependencies — @atheory-ai/kitsune.

debugModule →

@atheory-ai/kitsune/modules/storage

Storage capability module.

pnpm add @atheory-ai/kitsune

Exports

• storageModule(options?) → a module that handles storage commands
• StorageToken → provider token for the storage service
• memoryStorageAdapter(seed?) → test/SSR-friendly adapter
• StorageQuotaError
• Types: StorageModuleOptions, StorageAutosaveOptions, StorageAdapter, StorageService, StorageBackend, StorageCommandPayload, StorageCommandResult

Commands

• storage.write
• storage.read
• storage.delete
• storage.list
• storage.clear

Autosave

When storageModule({ autosave: true }) is installed, the module observes field.changed, writes a draft, and clears the draft on form.submit or form.reset. It also observes form.connected and emits storage.draft_loaded when a saved draft exists.

Dependencies — @atheory-ai/kitsune.

@atheory-ai/kitsune/modules/analytics

Analytics capability module.

pnpm add @atheory-ai/kitsune

Exports

• analyticsModule(options?) → a module that queues, tracks, and flushes analytics events
• AnalyticsToken → provider token for the analytics service
• memoryAnalyticsTransport() → test/SSR-friendly transport
• Types: AnalyticsModuleOptions, AnalyticsAutoTrackOptions, AnalyticsEvent, AnalyticsTransport, AnalyticsService, AnalyticsTrackInput, AnalyticsTrackResult, AnalyticsFlushResult

Commands

• analytics.track
• analytics.flush

Auto Tracking

When analyticsModule({ autoTrack: true }) is installed, the module observes runtime events and queues product events while ignoring internal analytics.*, storage.*, and runtime.* events.

Dependencies — @atheory-ai/kitsune.

@atheory-ai/kitsune/modules/audit

Audit trail capability module.

pnpm add @atheory-ai/kitsune

Exports

• auditModule(options?) → a module that records and queries audit entries
• AuditToken → provider token for the audit service
• memoryAuditStore(seed?) → test/SSR-friendly store
• Types: AuditModuleOptions, AuditAutoRecordOptions, AuditEntry, AuditActor, AuditStore, AuditService, AuditRecordInput, AuditRecordResult, AuditQuery

Commands

• audit.record
• audit.query
• audit.clear

Auto Recording

When auditModule({ autoRecord: true }) is installed, the module observes runtime events and records append-only audit entries while ignoring internal audit.*, analytics.*, observability.*, storage.*, and runtime.* events.

Dependencies — @atheory-ai/kitsune.

@atheory-ai/kitsune/modules/observability

Observability capability module.

pnpm add @atheory-ai/kitsune

Exports

• observabilityModule(options?) → a module that captures issues, breadcrumbs, and selected diagnostics
• ObservabilityToken → provider token for the observability service
• memoryObservabilityTransport() → test/SSR-friendly transport
• Types: ObservabilityModuleOptions, ObservabilityIssue, ObservabilityBreadcrumb, ObservabilityTransport, ObservabilityService, ObservabilityCaptureInput, ObservabilityCaptureResult, ObservabilityFlushResult, ObservabilitySeverity

Commands

• observability.capture
• observability.breadcrumb
• observability.flush

Diagnostics

When observabilityModule({ captureDiagnostics: true }) is installed, the module captures command.failed, event.handler_failed, and module.failed diagnostics as issues.

Dependencies — @atheory-ai/kitsune.

@atheory-ai/kitsune/modules/permissions

Permission-checking capability module.

pnpm add @atheory-ai/kitsune

Exports

• permissionsModule(options?) → a module that evaluates permission rules
• PermissionsToken → provider token for the permission service
• Types: PermissionsModuleOptions, PermissionInput, PermissionResult, PermissionRule, PermissionService

Commands

• permission.check

Dependencies — @atheory-ai/kitsune.

@atheory-ai/kitsune/modules/flags

Feature flag capability module.

pnpm add @atheory-ai/kitsune

Exports

• flagsModule(options?) → a module that evaluates local or provider-backed flags
• FlagsToken → provider token for the flag service
• Types: FlagsModuleOptions, FlagProvider, FlagService, FlagEvaluateInput, FlagEvaluateResult, FlagValue

Commands

• flag.evaluate
• flag.set

Dependencies — @atheory-ai/kitsune.

@atheory-ai/kitsune/modules/validation

Native form validation capability module.

pnpm add @atheory-ai/kitsune

Exports

• validationModule() → a module that validates native HTMLFormElement instances
• ValidationToken → provider token for the validation service
• Types: ValidationInput, ValidationIssue, ValidationResult, ValidationService

Commands

• form.validate

Dependencies — @atheory-ai/kitsune.

@atheory-ai/kitsune/modules/search

In-memory search capability module.

pnpm add @atheory-ai/kitsune

Exports

• searchModule() → a module that indexes and queries documents
• SearchToken → provider token for the search service
• Types: SearchDocument, SearchQuery, SearchResult, SearchService

Commands

• search.index
• search.remove
• search.query

Dependencies — @atheory-ai/kitsune.

@atheory-ai/kitsune/modules/sync

Runtime event sync capability module.

pnpm add @atheory-ai/kitsune

Exports

• syncModule(options?) → a module that queues selected runtime events and flushes them to a transport
• SyncToken → provider token for the sync service
• memorySyncTransport() → test/SSR-friendly transport
• Types: SyncModuleOptions, SyncRecord, SyncService, SyncTransport, MemorySyncTransport

Commands

• sync.flush

Event Sync

The module observes runtime events, skips internal module/runtime events, and supports include or exclude filters.

Dependencies — @atheory-ai/kitsune.

@atheory-ai/kitsune/modules/command-palette

Command palette registry capability module.

pnpm add @atheory-ai/kitsune

Exports

• commandPaletteModule(options?) → a module that registers, searches, and runs command actions
• CommandPaletteToken → provider token for the command palette service
• Types: CommandPaletteAction, CommandPaletteModuleOptions, CommandPaletteService

Commands

• command_palette.register
• command_palette.search
• command_palette.run

Dependencies — @atheory-ai/kitsune.

Acceptance fixtures

Two private packages are used by the workspace for golden-test acceptance:

• @atheory-ai/kitsune-acceptance — native browser fixtures
• @atheory-ai/kitsune-react-acceptance — React fixtures

These aren’t published; they exercise the published packages end-to-end.

Modular installs

Use the umbrella package when you want one install target:

pnpm add @atheory-ai/kitsune

Use the individual packages when you want tighter dependency boundaries:

pnpm add @atheory-ai/kitsune-core @atheory-ai/kitsune-app @atheory-ai/kitsune-ui
pnpm add -D @atheory-ai/kitsune-dev