@nice-code/state 0.3.3

package/build/types/devtools/browser/components/ChangeList.d.ts

@@ -0,0 +1,9 @@
+import type { CSSProperties } from "react";
+import type { IDevtoolsStateChange } from "../../core/StateDevtools.types";
+export declare function ChangeList({ changes, selectedCuid, onSelect, showStore, style, }: {
+    changes: IDevtoolsStateChange[];
+    selectedCuid: string | null;
+    onSelect: (cuid: string) => void;
+    showStore: boolean;
+    style?: CSSProperties;
+}): import("react/jsx-runtime").JSX.Element;

package/build/types/devtools/browser/components/DiffView.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Test-framework-style diff: only the paths that changed, with removed values in
+ * error red on a `−` line and added values in success green on a `+` line. A
+ * `changed` entry renders both lines so old → new reads top-to-bottom.
+ */
+export declare function DiffView({ before, after }: {
+    before: unknown;
+    after: unknown;
+}): import("react/jsx-runtime").JSX.Element;

package/build/types/devtools/browser/components/JsonView.d.ts

@@ -0,0 +1,7 @@
+import type { CSSProperties } from "react";
+export declare function renderColoredJson(text: string): React.ReactNode[];
+export declare function JsonView({ value, indent, style, }: {
+    value: unknown;
+    indent?: number;
+    style?: CSSProperties;
+}): import("react/jsx-runtime").JSX.Element;

package/build/types/devtools/browser/components/PanelChrome.d.ts

@@ -0,0 +1,54 @@
+import { type ReactNode } from "react";
+import type { TDevtoolsPosition } from "../../core/StateDevtools.types";
+export type TDockSide = "top" | "bottom" | "left" | "right";
+export declare function getDockSide(pos: TDevtoolsPosition): TDockSide;
+export interface IDevtoolsLauncherItem {
+    id: string;
+    label: string;
+    icon: string;
+    badge?: string;
+    onOpen: () => void;
+}
+export declare function PanelHeader({ position, onPositionChange, onClose, onClear, paused, onTogglePause, openOthers, children, }: {
+    position: TDevtoolsPosition;
+    onPositionChange: (p: TDevtoolsPosition) => void;
+    onClose: () => void;
+    onClear?: () => void;
+    paused: boolean;
+    onTogglePause: () => void;
+    openOthers?: IDevtoolsLauncherItem[];
+    children?: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function ResizeHandle({ dockSide, dockedSize, onChange, }: {
+    dockSide: TDockSide;
+    dockedSize: number;
+    onChange: (size: number) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Draggable divider between the list and the detail pane. `horizontal` refers to
+ * the split axis: a row layout (dock top/bottom) splits horizontally and drags
+ * left/right; a column layout (dock left/right) splits vertically. The reported
+ * ratio is the fraction of the container the *detail* pane should occupy.
+ */
+export declare function SplitHandle({ horizontal, onRatioChange, }: {
+    horizontal: boolean;
+    onRatioChange: (ratio: number) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/** A compact segmented toggle used for the Timeline / State mode switch. */
+export declare function SegmentedControl<T extends string>({ options, value, onChange, }: {
+    options: {
+        value: T;
+        label: string;
+    }[];
+    value: T;
+    onChange: (value: T) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * The combined, page-wide launcher shown while every devtool is collapsed — one
+ * grouped pill with a segment per registered devtool, so the buttons never
+ * overlap or hide behind each other. Rendered by the coordinator's "primary"
+ * devtool only.
+ */
+export declare function DevtoolsLauncher({ items }: {
+    items: IDevtoolsLauncherItem[];
+}): import("react/jsx-runtime").JSX.Element;

package/build/types/devtools/browser/components/SectionLabel.d.ts

@@ -0,0 +1,4 @@
+export declare function SectionLabel({ label, color, }: {
+    label: string;
+    color?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/build/types/devtools/browser/components/StateInspector.d.ts

@@ -0,0 +1,16 @@
+import type { IDevtoolsStoreInfo } from "../../core/StateDevtools.types";
+/**
+ * Live current-state view (top half) plus a direct JSON editor (bottom half) for
+ * one store — a fixed 50/50 split so the editor is usable without manual
+ * resizing. Editing is the "trigger edits directly for testing" capability: the
+ * draft is parsed and handed to {@link StateDevtoolsCore.applyEdit}, which
+ * replaces the store state.
+ *
+ * The draft is seeded from the live state only while it is clean — once the user
+ * types, incoming external updates no longer clobber their edit (a "reload"
+ * button re-syncs on demand).
+ */
+export declare function StateInspector({ store, onApply, }: {
+    store: IDevtoolsStoreInfo;
+    onApply: (storeId: string, newState: unknown) => void;
+}): import("react/jsx-runtime").JSX.Element;

package/build/types/devtools/browser/components/StoreTabs.d.ts

@@ -0,0 +1,12 @@
+import type { IDevtoolsStoreInfo } from "../../core/StateDevtools.types";
+/**
+ * Horizontal store filter. `null` selection means "all stores". When
+ * `includeAll` is false (the State inspector needs a concrete store) the All
+ * pill is omitted.
+ */
+export declare function StoreTabs({ stores, selectedStoreId, onSelect, includeAll, }: {
+    stores: IDevtoolsStoreInfo[];
+    selectedStoreId: string | null;
+    onSelect: (id: string | null) => void;
+    includeAll?: boolean;
+}): import("react/jsx-runtime").JSX.Element;

package/build/types/devtools/browser/components/utils.d.ts

@@ -0,0 +1,29 @@
+import type { Patch } from "immer";
+import type { IDevtoolsStateChange, TStateChangeSource } from "../../core/StateDevtools.types";
+export declare function safeStringify(value: unknown, indent?: number): string;
+export declare function formatTimestamp(ms: number): string;
+export declare function formatRelativeAge(ms: number): string;
+export declare const SOURCE_LABEL: Record<TStateChangeSource, string>;
+export declare const SOURCE_COLOR: Record<TStateChangeSource, string>;
+/** Render an Immer patch path (`["todos", 0, "done"]`) as `todos.0.done`. */
+export declare function patchPathToString(path: Patch["path"]): string;
+/**
+ * A terse, single-line summary of what a change touched, for the timeline row.
+ * Prefers a `path: prev → next` form for single scalar replaces, otherwise lists
+ * the distinct top-level paths affected.
+ */
+export declare function summarizeChange(change: IDevtoolsStateChange): string;
+export type TDiffKind = "added" | "removed" | "changed";
+export interface IDiffEntry {
+    path: string;
+    kind: TDiffKind;
+    before?: unknown;
+    after?: unknown;
+}
+/**
+ * Structural diff between two snapshots, flattened to the individual leaf/branch
+ * paths that actually changed — the data behind the test-framework-style "Diff"
+ * view. Unchanged branches are skipped entirely (Immer's structural sharing
+ * means equal branches keep their reference, so this stays cheap).
+ */
+export declare function computeDiff(before: unknown, after: unknown): IDiffEntry[];

package/build/types/devtools/browser/devtools_dock.d.ts

@@ -0,0 +1,47 @@
+export type TDockSide = "top" | "bottom" | "left" | "right";
+/** A handle to one registered devtool, used to render launch controls. */
+export interface IDockDevtoolRef {
+    id: string;
+    label: string;
+    icon: string;
+    badge?: string;
+    onOpen: () => void;
+}
+/** The live, syncable part of a devtool's registration. */
+export interface IDockDevtoolSync {
+    side: TDockSide;
+    size: number;
+    open: boolean;
+    badge?: string;
+}
+export interface IDockDevtoolInput extends IDockDevtoolSync {
+    id: string;
+    label: string;
+    icon: string;
+    onOpen: () => void;
+}
+export interface IDockView {
+    /** Offset (px) from the docked edge — stacks open panels on the same side. */
+    dockOffset: number;
+    /** Is any devtool on the page currently open? */
+    anyOpen: boolean;
+    /** First-registered devtool — the one that renders the combined launcher. */
+    isPrimary: boolean;
+    /** Every registered devtool, for the combined launcher. */
+    devtools: IDockDevtoolRef[];
+    /** Closed devtools other than this one, for an open panel's header. */
+    otherClosed: IDockDevtoolRef[];
+}
+export interface IDevtoolsDockCoordinator {
+    version: number;
+    register(panel: IDockDevtoolInput): () => void;
+    update(id: string, next: IDockDevtoolSync): void;
+    getView(id: string): IDockView;
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Returns the page-wide dock coordinator, installing it on `window` the first
+ * time it is requested. On the server (no `window`) a throwaway instance is
+ * returned so callers can use it unconditionally.
+ */
+export declare function getDevtoolsDockCoordinator(): IDevtoolsDockCoordinator;

package/build/types/devtools/browser/index.d.ts

@@ -0,0 +1,3 @@
+export type { IDevtoolsStateChange, IDevtoolsStoreInfo, IStateDevtoolsSnapshot, TDevtoolsPosition, TStateChangeSource, TStateDevtoolsListener, } from "../core/StateDevtools.types";
+export { type IStateDevtoolsCoreOptions, StateDevtoolsCore, } from "../core/StateDevtoolsCore";
+export { type INiceStateDevtoolsProps, NiceStateDevtools } from "./NiceStateDevtools";

package/build/types/devtools/core/StateDevtools.types.d.ts

@@ -0,0 +1,43 @@
+import type { Patch } from "immer";
+export type TDevtoolsPosition = "dock-bottom" | "dock-top" | "dock-left" | "dock-right";
+/**
+ * How a recorded change came to be. `update` is the normal Immer-patch path,
+ * `replace` is a whole-state swap with no patches, and the two `devtools-*`
+ * sources are writes the devtools itself made (manual edits / reverts) so they
+ * can be visually distinguished from real app traffic.
+ */
+export type TStateChangeSource = "update" | "replace" | "devtools-edit" | "devtools-revert";
+/**
+ * A single committed mutation of a registered store. Captures both the Immer
+ * patches (when available) and full before/after snapshots so the panel can
+ * render a precise diff and offer a one-click revert.
+ */
+export interface IDevtoolsStateChange {
+    cuid: string;
+    storeId: string;
+    storeLabel: string;
+    timestamp: number;
+    patches: Patch[];
+    inversePatches: Patch[];
+    prevSnapshot: unknown;
+    snapshot: unknown;
+    source: TStateChangeSource;
+}
+/**
+ * Live summary of a registered store, refreshed on every commit so the panel's
+ * tabs and state inspector always reflect the current value.
+ */
+export interface IDevtoolsStoreInfo {
+    id: string;
+    label: string;
+    currentState: unknown;
+    changeCount: number;
+    lastChangeTime?: number;
+}
+export interface IStateDevtoolsSnapshot {
+    stores: IDevtoolsStoreInfo[];
+    /** Most-recent-first across all registered stores. */
+    changes: IDevtoolsStateChange[];
+    paused: boolean;
+}
+export type TStateDevtoolsListener = (snapshot: IStateDevtoolsSnapshot) => void;

package/build/types/devtools/core/StateDevtoolsCore.d.ts

@@ -0,0 +1,56 @@
+import type { Store } from "../../core/Store";
+import type { IDevtoolsStateChange, IStateDevtoolsSnapshot, TStateDevtoolsListener } from "./StateDevtools.types";
+export interface IStateDevtoolsCoreOptions {
+    /** Cap on retained changes across all stores (oldest dropped first). */
+    maxChanges?: number;
+}
+/**
+ * Framework-agnostic collector for nice-state stores.
+ *
+ * Register any {@link Store} and the core hooks its patch + update streams,
+ * pairing the two so each committed mutation becomes a single
+ * {@link IDevtoolsStateChange} with patches and full before/after snapshots.
+ * The browser panel ({@link NiceStateDevtools}) renders whatever this exposes.
+ *
+ * Registering a store attaches a patch listener, which makes Immer compute
+ * patches for that store's updates — a negligible dev-time cost. Keep this out
+ * of production bundles (the panel is dev-gated, but the core is not).
+ */
+export declare class StateDevtoolsCore {
+    private readonly _stores;
+    private _changes;
+    private readonly _listeners;
+    private readonly _maxChanges;
+    private _paused;
+    private _cuidCounter;
+    private _sourceOverride;
+    constructor(options?: IStateDevtoolsCoreOptions);
+    /**
+     * Start observing a store under a human-readable label. Returns an
+     * unregister function. If the label collides with an existing store, a numeric
+     * suffix is appended to keep ids unique.
+     */
+    registerStore(label: string, store: Store<any>): () => void;
+    unregisterStore(id: string): void;
+    /**
+     * Replace a registered store's state wholesale — the primary "edit directly
+     * for testing" entry point. The resulting change is tagged `devtools-edit`.
+     */
+    applyEdit(storeId: string, newState: unknown): void;
+    /**
+     * Undo a change by applying its inverse patches. Cleanest for the most recent
+     * change of a store; older reverts may not apply if later changes touched the
+     * same paths. The resulting change is tagged `devtools-revert`.
+     */
+    revertChange(change: IDevtoolsStateChange): void;
+    setPaused(paused: boolean): void;
+    togglePaused(): void;
+    /** Drop the recorded timeline; registered stores and their state remain. */
+    clear(): void;
+    getSnapshot(): IStateDevtoolsSnapshot;
+    subscribe(listener: TStateDevtoolsListener): () => void;
+    private _recordChange;
+    private _uniqueId;
+    private _buildSnapshot;
+    private _notify;
+}

package/build/types/devtools/core/devtools_colors.d.ts

@@ -0,0 +1,26 @@
+export declare const DEVTOOL_COLOR_SEMANTIC_ERROR = "#FF5C5C";
+export declare const DEVTOOL_COLOR_SEMANTIC_SUCCESS = "#A3E635";
+export declare const DEVTOOL_COLOR_SEMANTIC_SYSTEM = "#38BDF8";
+export declare const DEVTOOL_COLOR_SEMANTIC_WARNING = "#FB923C";
+export declare const DEVTOOL_COLOR_SEMANTIC_METADATA = "#A1A1AA";
+export declare const DEVTOOL_COLOR_TEXT_EMPHASIS = "#f1f5f9";
+export declare const DEVTOOL_COLOR_TEXT_SECONDARY = "#cbd5e1";
+export declare const DEVTOOL_COLOR_TEXT_MUTED = "#64748b";
+export declare const DEVTOOL_COLOR_TEXT_FAINT = "#334155";
+export declare const DEVTOOL_LIST_BASE_BACKGROUND = "#0f172a";
+export declare const DEVTOOL_LIST_SELECTED_BACKGROUND = "#1d2942";
+export declare const DEVTOOL_DETAIL_BASE_BACKGROUND = "#0d1729";
+export declare const DEVTOOL_DETAIL_HEADER_BACKGROUND = "#131f35";
+export declare const DEVTOOL_SECTION_BACKGROUND = "#1e293b";
+export declare const DEVTOOL_SECTION_STRING_BACKGROUND = "#0d131f";
+export declare const DEVTOOL_PANEL_BORDER = "#1e293b";
+export declare const DEVTOOL_PANEL_DIVIDER_BORDER = "#1d3352";
+export declare const DEVTOOL_EDITOR_BACKGROUND = "#08101f";
+export declare const DEVTOOL_ERROR_BACKGROUND = "#1e0a0a";
+export declare const DEVTOOL_JSON_KEY = "#a5b4fc";
+export declare const DEVTOOL_JSON_STRING = "#fbbf24";
+export declare const DEVTOOL_JSON_NUMBER = "#34d399";
+export declare const DEVTOOL_JSON_KEYWORD = "#a78bfa";
+export declare const DEVTOOL_JSON_PUNCTUATION = "#475569";
+export declare const MONO_FONT = "ui-monospace, 'Cascadia Code', 'Source Code Pro', monospace";
+export declare const SANS_FONT = "ui-sans-serif, system-ui, sans-serif";

package/build/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./core";

package/build/types/react/InjectStoreState.d.ts

@@ -0,0 +1,18 @@
+import type { ReactElement } from "react";
+import type { Store } from "../core/Store";
+import { type TEqualityFn } from "./useStoreState";
+export interface IPropsInjectStoreState<S extends object, SS> {
+    store: Store<S>;
+    on?: (state: S) => SS;
+    /**
+     * Optional equality function for the selected slice. Defaults to a strict
+     * reference check; pass `deepEqual` from `fast-equals` for inline objects.
+     */
+    equalityFn?: TEqualityFn<SS>;
+    children: (output: SS) => ReactElement;
+}
+/**
+ * Render-prop binding: subscribes to `store` (optionally narrowed by `on`) and
+ * renders `children` with the selected slice.
+ */
+export declare function InjectStoreState<S extends object, SS = S>({ store, on, equalityFn, children, }: IPropsInjectStoreState<S, SS>): ReactElement;

package/build/types/react/index.d.ts

@@ -0,0 +1,3 @@
+export { InjectStoreState, type IPropsInjectStoreState } from "./InjectStoreState";
+export { useLocalStore } from "./useLocalStore";
+export { type TEqualityFn, useStoreState } from "./useStoreState";

package/build/types/react/useLocalStore.d.ts

@@ -0,0 +1,8 @@
+import { Store } from "../core/Store";
+/**
+ * Create a component-local {@link Store} that persists across renders. Passing a
+ * `deps` array re-creates the store (with a fresh initial state) whenever the
+ * dependencies change by shallow comparison.
+ */
+declare function useLocalStore<S extends object>(initialState: (() => S) | S, deps?: ReadonlyArray<unknown>): Store<S>;
+export { useLocalStore };

package/build/types/react/useStoreState.d.ts

@@ -0,0 +1,23 @@
+import type { Store } from "../core/Store";
+/**
+ * Compares the previously selected value against the next one. Returning `true`
+ * tells the hook the value is unchanged, so React is handed the *same*
+ * reference and no re-render is scheduled.
+ */
+export type TEqualityFn<SS> = (a: SS, b: SS) => boolean;
+/**
+ * Subscribe a React component to a store, optionally narrowing to a derived
+ * slice.
+ *
+ * Built on `useSyncExternalStore`, so it is tear-free under React 18+
+ * concurrent rendering with no manual `useState`/`useEffect` subscription loop.
+ *
+ * A `useRef` cache holds the last selected value. On every store emission the
+ * selector is re-evaluated and the result is run through a strict-reference
+ * fast-path first; only if the reference differs is `equalityFn` consulted. A
+ * new reference is handed back to React exclusively when a genuine change is
+ * detected, so equal-but-new selector results never trigger a render.
+ */
+declare function useStoreState<S extends object>(store: Store<S>): S;
+declare function useStoreState<S extends object, SS>(store: Store<S>, getSubState: (state: S) => SS, equalityFn?: TEqualityFn<SS>): SS;
+export { useStoreState };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@nice-code/state",
+  "version": "0.3.3",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./build/types/index.d.ts",
+      "import": "./build/index.js"
+    },
+    "./react": {
+      "source": "./src/react/index.ts",
+      "types": "./build/types/react/index.d.ts",
+      "import": "./build/react/index.js"
+    },
+    "./devtools/browser": {
+      "source": "./src/devtools/browser/index.ts",
+      "types": "./build/types/devtools/browser/index.d.ts",
+      "import": "./build/devtools/browser/index.js"
+    }
+  },
+  "files": [
+    "build",
+    "package.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "type-check": "bunx tsc --noEmit",
+    "type-check-watch": "bunx tsc --noEmit --watch",
+    "clean-build": "bunx rimraf build",
+    "vitest": "vitest --typecheck",
+    "vitest-agent": "vitest --typecheck --reporter=agent",
+    "build": "bun run clean-build && bun run build.ts && bun run build-types",
+    "build-watch": "bun run clean-build && bun run build.ts --watch && bun run build-types --watch",
+    "build-types": "tsc --project tsconfig.build.json"
+  },
+  "dependencies": {
+    "immer": "11.1.8",
+    "fast-equals": "6.0.0"
+  },
+  "devDependencies": {
+    "react": "19.2.7"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}