@nonsoanetoh/lil-gui-helper 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,131 @@
+import * as React from 'react';
+
+type GuiRoute = "*" | `/${string}`;
+type GuiItemBase = {
+    id?: string;
+    name: string;
+    routes?: GuiRoute[];
+};
+type GuiItemNumber = GuiItemBase & {
+    type: "number";
+    value: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    onChange: (value: number) => void;
+};
+type GuiItemColor = GuiItemBase & {
+    type: "color";
+    value: string;
+    onChange: (value: string) => void;
+};
+type GuiItemBoolean = GuiItemBase & {
+    type: "boolean";
+    value: boolean;
+    onChange: (value: boolean) => void;
+};
+type GuiItemString = GuiItemBase & {
+    type: "string";
+    value: string;
+    onChange: (value: string) => void;
+};
+type GuiItemDropdown = GuiItemBase & {
+    type: "dropdown";
+    value: string;
+    options: string[] | Record<string, string>;
+    onChange: (value: string) => void;
+};
+type GuiItemFolder = GuiItemBase & {
+    type: "folder";
+    children: GuiItem[];
+};
+type GuiItem = GuiItemNumber | GuiItemColor | GuiItemBoolean | GuiItemString | GuiItemDropdown | GuiItemFolder;
+type SettingDefinitionValue = string | number | boolean;
+type SettingDefinitionBase = {
+    id: string;
+    name: string;
+    default: SettingDefinitionValue;
+    routes?: GuiRoute[];
+};
+type SettingDefinition = (SettingDefinitionBase & {
+    type: "color";
+}) | (SettingDefinitionBase & {
+    type: "number";
+    min?: number;
+    max?: number;
+    step?: number;
+}) | (SettingDefinitionBase & {
+    type: "boolean";
+}) | (SettingDefinitionBase & {
+    type: "string";
+}) | (SettingDefinitionBase & {
+    type: "dropdown";
+    options: string[] | Record<string, string>;
+});
+type SettingDefinitionFolder = {
+    type: "folder";
+    name: string;
+    routes?: GuiRoute[];
+    children: SettingDefinition[];
+};
+type SettingDefinitionItem = SettingDefinition | SettingDefinitionFolder;
+type SettingPrimitive = number | string | boolean;
+type SettingValue = SettingPrimitive | SettingsGroup;
+interface SettingsGroup {
+    [key: string]: SettingValue;
+}
+type Settings = Record<string, SettingsGroup>;
+type SettingsContextValue = {
+    settings: Settings;
+    updateSetting: (path: string, value: SettingValue) => void;
+    getSetting: <T extends SettingValue = SettingValue>(path: string) => T | undefined;
+    getGroup: (name: string) => SettingsGroup;
+};
+
+type SettingsProviderProps = {
+    children: React.ReactNode;
+    initialSettings?: Partial<Settings>;
+};
+declare function SettingsProvider({ children, initialSettings }: SettingsProviderProps): React.FunctionComponentElement<React.ProviderProps<SettingsContextValue | null>>;
+declare function useSettings(): SettingsContextValue;
+
+declare function matchRoute(pathname: string, route: GuiRoute): boolean;
+declare function getDefinitionsForRoute(definitions: SettingDefinitionItem[], pathname: string): SettingDefinitionItem[];
+declare function getDefinition(definitions: SettingDefinitionItem[], id: string): SettingDefinition | undefined;
+
+type GuiConfigProviderProps = {
+    definitions: SettingDefinitionItem[];
+    children: React.ReactNode;
+};
+declare function GuiConfigProvider({ definitions, children }: GuiConfigProviderProps): React.FunctionComponentElement<React.ProviderProps<SettingDefinitionItem[]>>;
+declare function useGuiDefinitions(): SettingDefinitionItem[];
+declare function useGetDefinition(): (id: string) => ReturnType<typeof getDefinition>;
+
+type GuiProviderProps = {
+    children: React.ReactNode;
+    visible?: boolean;
+};
+declare function GuiProvider({ children, visible, }: GuiProviderProps): React.FunctionComponentElement<React.ProviderProps<boolean>>;
+declare function useGuiVisible(): boolean;
+
+declare function GuiManager(): React.DetailedReactHTMLElement<{
+    ref: React.RefObject<HTMLDivElement | null>;
+    style: {
+        position: "fixed";
+        top: number;
+        right: number;
+        zIndex: number;
+    };
+}, HTMLDivElement> | null;
+
+type UseSettingOptions<T extends SettingDefinitionValue = SettingDefinitionValue> = {
+    default?: T;
+    onChange?: (value: T) => void;
+};
+declare function useSetting<T extends SettingDefinitionValue = SettingDefinitionValue>(path: string, defaultOrOptions?: T | UseSettingOptions<T>, onChange?: (value: T) => void): T | undefined;
+
+type GetSetting = (path: string) => unknown;
+type UpdateSetting = (path: string, value: SettingDefinitionValue) => void;
+declare function buildGuiItemsFromDefinitions(definitions: SettingDefinitionItem[], pathname: string, getSetting: GetSetting, updateSetting: UpdateSetting): GuiItem[];
+
+export { GuiConfigProvider, type GuiConfigProviderProps, type GuiItem, GuiManager, GuiProvider, type GuiProviderProps, type GuiRoute, type SettingDefinition, type SettingDefinitionBase, type SettingDefinitionFolder, type SettingDefinitionItem, type SettingDefinitionValue, type SettingValue, type Settings, type SettingsContextValue, SettingsProvider, type SettingsProviderProps, type UseSettingOptions, buildGuiItemsFromDefinitions, getDefinition, getDefinitionsForRoute, matchRoute, useGetDefinition, useGuiDefinitions, useGuiVisible, useSetting, useSettings };

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+import * as React from 'react';
+
+type GuiRoute = "*" | `/${string}`;
+type GuiItemBase = {
+    id?: string;
+    name: string;
+    routes?: GuiRoute[];
+};
+type GuiItemNumber = GuiItemBase & {
+    type: "number";
+    value: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    onChange: (value: number) => void;
+};
+type GuiItemColor = GuiItemBase & {
+    type: "color";
+    value: string;
+    onChange: (value: string) => void;
+};
+type GuiItemBoolean = GuiItemBase & {
+    type: "boolean";
+    value: boolean;
+    onChange: (value: boolean) => void;
+};
+type GuiItemString = GuiItemBase & {
+    type: "string";
+    value: string;
+    onChange: (value: string) => void;
+};
+type GuiItemDropdown = GuiItemBase & {
+    type: "dropdown";
+    value: string;
+    options: string[] | Record<string, string>;
+    onChange: (value: string) => void;
+};
+type GuiItemFolder = GuiItemBase & {
+    type: "folder";
+    children: GuiItem[];
+};
+type GuiItem = GuiItemNumber | GuiItemColor | GuiItemBoolean | GuiItemString | GuiItemDropdown | GuiItemFolder;
+type SettingDefinitionValue = string | number | boolean;
+type SettingDefinitionBase = {
+    id: string;
+    name: string;
+    default: SettingDefinitionValue;
+    routes?: GuiRoute[];
+};
+type SettingDefinition = (SettingDefinitionBase & {
+    type: "color";
+}) | (SettingDefinitionBase & {
+    type: "number";
+    min?: number;
+    max?: number;
+    step?: number;
+}) | (SettingDefinitionBase & {
+    type: "boolean";
+}) | (SettingDefinitionBase & {
+    type: "string";
+}) | (SettingDefinitionBase & {
+    type: "dropdown";
+    options: string[] | Record<string, string>;
+});
+type SettingDefinitionFolder = {
+    type: "folder";
+    name: string;
+    routes?: GuiRoute[];
+    children: SettingDefinition[];
+};
+type SettingDefinitionItem = SettingDefinition | SettingDefinitionFolder;
+type SettingPrimitive = number | string | boolean;
+type SettingValue = SettingPrimitive | SettingsGroup;
+interface SettingsGroup {
+    [key: string]: SettingValue;
+}
+type Settings = Record<string, SettingsGroup>;
+type SettingsContextValue = {
+    settings: Settings;
+    updateSetting: (path: string, value: SettingValue) => void;
+    getSetting: <T extends SettingValue = SettingValue>(path: string) => T | undefined;
+    getGroup: (name: string) => SettingsGroup;
+};
+
+type SettingsProviderProps = {
+    children: React.ReactNode;
+    initialSettings?: Partial<Settings>;
+};
+declare function SettingsProvider({ children, initialSettings }: SettingsProviderProps): React.FunctionComponentElement<React.ProviderProps<SettingsContextValue | null>>;
+declare function useSettings(): SettingsContextValue;
+
+declare function matchRoute(pathname: string, route: GuiRoute): boolean;
+declare function getDefinitionsForRoute(definitions: SettingDefinitionItem[], pathname: string): SettingDefinitionItem[];
+declare function getDefinition(definitions: SettingDefinitionItem[], id: string): SettingDefinition | undefined;
+
+type GuiConfigProviderProps = {
+    definitions: SettingDefinitionItem[];
+    children: React.ReactNode;
+};
+declare function GuiConfigProvider({ definitions, children }: GuiConfigProviderProps): React.FunctionComponentElement<React.ProviderProps<SettingDefinitionItem[]>>;
+declare function useGuiDefinitions(): SettingDefinitionItem[];
+declare function useGetDefinition(): (id: string) => ReturnType<typeof getDefinition>;
+
+type GuiProviderProps = {
+    children: React.ReactNode;
+    visible?: boolean;
+};
+declare function GuiProvider({ children, visible, }: GuiProviderProps): React.FunctionComponentElement<React.ProviderProps<boolean>>;
+declare function useGuiVisible(): boolean;
+
+declare function GuiManager(): React.DetailedReactHTMLElement<{
+    ref: React.RefObject<HTMLDivElement | null>;
+    style: {
+        position: "fixed";
+        top: number;
+        right: number;
+        zIndex: number;
+    };
+}, HTMLDivElement> | null;
+
+type UseSettingOptions<T extends SettingDefinitionValue = SettingDefinitionValue> = {
+    default?: T;
+    onChange?: (value: T) => void;
+};
+declare function useSetting<T extends SettingDefinitionValue = SettingDefinitionValue>(path: string, defaultOrOptions?: T | UseSettingOptions<T>, onChange?: (value: T) => void): T | undefined;
+
+type GetSetting = (path: string) => unknown;
+type UpdateSetting = (path: string, value: SettingDefinitionValue) => void;
+declare function buildGuiItemsFromDefinitions(definitions: SettingDefinitionItem[], pathname: string, getSetting: GetSetting, updateSetting: UpdateSetting): GuiItem[];
+
+export { GuiConfigProvider, type GuiConfigProviderProps, type GuiItem, GuiManager, GuiProvider, type GuiProviderProps, type GuiRoute, type SettingDefinition, type SettingDefinitionBase, type SettingDefinitionFolder, type SettingDefinitionItem, type SettingDefinitionValue, type SettingValue, type Settings, type SettingsContextValue, SettingsProvider, type SettingsProviderProps, type UseSettingOptions, buildGuiItemsFromDefinitions, getDefinition, getDefinitionsForRoute, matchRoute, useGetDefinition, useGuiDefinitions, useGuiVisible, useSetting, useSettings };

package/dist/index.js

@@ -0,0 +1,299 @@
+"use strict";
+"use client";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.tsx
+var index_exports = {};
+__export(index_exports, {
+  GuiConfigProvider: () => GuiConfigProvider,
+  GuiManager: () => GuiManager,
+  GuiProvider: () => GuiProvider,
+  SettingsProvider: () => SettingsProvider,
+  buildGuiItemsFromDefinitions: () => buildGuiItemsFromDefinitions,
+  getDefinition: () => getDefinition,
+  getDefinitionsForRoute: () => getDefinitionsForRoute,
+  matchRoute: () => matchRoute,
+  useGetDefinition: () => useGetDefinition,
+  useGuiDefinitions: () => useGuiDefinitions,
+  useGuiVisible: () => useGuiVisible,
+  useSetting: () => useSetting,
+  useSettings: () => useSettings
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/settings-context.tsx
+var React = __toESM(require("react"));
+function getByPath(obj, path) {
+  const parts = path.split(".").filter(Boolean);
+  let current = obj;
+  for (const key of parts) {
+    if (current == null || typeof current !== "object" || Array.isArray(current)) return void 0;
+    current = current[key];
+  }
+  return current;
+}
+function setByPath(obj, path, value) {
+  const parts = path.split(".").filter(Boolean);
+  if (parts.length === 0) return obj;
+  const result = { ...obj };
+  let current = result;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i];
+    const next = current[key];
+    const nextObj = next != null && typeof next === "object" && !Array.isArray(next) ? { ...next } : {};
+    current[key] = nextObj;
+    current = nextObj;
+  }
+  current[parts[parts.length - 1]] = value;
+  return result;
+}
+var SettingsContext = React.createContext(null);
+function SettingsProvider({ children, initialSettings = {} }) {
+  const [settings, setSettings] = React.useState(() => {
+    const result = {};
+    for (const key in initialSettings) {
+      const group = initialSettings[key];
+      if (group !== void 0) result[key] = group;
+    }
+    return result;
+  });
+  const updateSetting = React.useCallback((path, value2) => {
+    setSettings((prev) => setByPath(prev, path, value2));
+  }, []);
+  const getSetting = React.useCallback(
+    (path) => getByPath(settings, path),
+    [settings]
+  );
+  const getGroup = React.useCallback((name) => settings[name] ?? {}, [settings]);
+  const value = React.useMemo(
+    () => ({ settings, updateSetting, getSetting, getGroup }),
+    [settings, updateSetting, getSetting, getGroup]
+  );
+  return React.createElement(SettingsContext.Provider, { value }, children);
+}
+function useSettings() {
+  const ctx = React.useContext(SettingsContext);
+  if (!ctx) throw new Error("useSettings must be used within SettingsProvider");
+  return ctx;
+}
+
+// src/config-context.tsx
+var React2 = __toESM(require("react"));
+
+// src/routes.ts
+function matchRoute(pathname, route) {
+  if (route === "*") return true;
+  if (route.endsWith("/*")) {
+    const prefix = route.slice(0, -2);
+    return pathname.startsWith(prefix + "/");
+  }
+  return pathname === route;
+}
+function getDefinitionsForRoute(definitions, pathname) {
+  return definitions.filter((def) => {
+    const routes = def.routes;
+    if (!routes?.length) return true;
+    return routes.some((r) => matchRoute(pathname, r));
+  });
+}
+function flatten(items, acc = /* @__PURE__ */ new Map()) {
+  for (const d of items) {
+    if (d.type === "folder") flatten(d.children, acc);
+    else if (d.id != null) acc.set(d.id, d);
+  }
+  return acc;
+}
+function getDefinition(definitions, id) {
+  return flatten(definitions).get(id);
+}
+
+// src/config-context.tsx
+var DefinitionsContext = React2.createContext([]);
+function GuiConfigProvider({ definitions, children }) {
+  const value = React2.useMemo(() => definitions, [definitions]);
+  return React2.createElement(DefinitionsContext.Provider, { value }, children);
+}
+function useGuiDefinitions() {
+  return React2.useContext(DefinitionsContext);
+}
+function useGetDefinition() {
+  const definitions = useGuiDefinitions();
+  return React2.useCallback((id) => getDefinition(definitions, id), [definitions]);
+}
+
+// src/gui-provider.tsx
+var React3 = __toESM(require("react"));
+var GuiVisibilityContext = React3.createContext(false);
+function GuiProvider({
+  children,
+  visible = true
+}) {
+  const value = React3.useMemo(() => !!visible, [visible]);
+  return React3.createElement(GuiVisibilityContext.Provider, { value }, children);
+}
+function useGuiVisible() {
+  return React3.useContext(GuiVisibilityContext);
+}
+
+// src/gui-manager.tsx
+var React4 = __toESM(require("react"));
+var import_navigation = require("next/navigation");
+var import_lil_gui = __toESM(require("lil-gui"));
+
+// src/builder.ts
+function buildGuiItemsFromDefinitions(definitions, pathname, getSetting, updateSetting) {
+  const forRoute = getDefinitionsForRoute(definitions, pathname);
+  return forRoute.map((def) => definitionToGuiItem(def, getSetting, updateSetting));
+}
+function definitionToGuiItem(def, getSetting, updateSetting) {
+  if (def.type === "folder") {
+    return {
+      type: "folder",
+      name: def.name,
+      children: def.children.map((c) => definitionToGuiItem(c, getSetting, updateSetting))
+    };
+  }
+  const value = getSetting(def.id) ?? def.default;
+  switch (def.type) {
+    case "color":
+      return { type: "color", id: def.id, name: def.name, value, onChange: (v) => updateSetting(def.id, v) };
+    case "number":
+      return { type: "number", id: def.id, name: def.name, value, min: def.min, max: def.max, step: def.step, onChange: (v) => updateSetting(def.id, v) };
+    case "boolean":
+      return { type: "boolean", id: def.id, name: def.name, value, onChange: (v) => updateSetting(def.id, v) };
+    case "string":
+      return { type: "string", id: def.id, name: def.name, value, onChange: (v) => updateSetting(def.id, v) };
+    case "dropdown":
+      return { type: "dropdown", id: def.id, name: def.name, value, options: def.options, onChange: (v) => updateSetting(def.id, v) };
+  }
+}
+
+// src/gui-manager.tsx
+function addItem(gui, item) {
+  if (item.type === "folder") {
+    const folder = gui.addFolder(item.name);
+    for (const child of item.children) addItem(folder, child);
+    return;
+  }
+  const obj = { value: item.value };
+  let controller;
+  switch (item.type) {
+    case "number":
+      controller = gui.add(obj, "value", item.min ?? 0, item.max ?? 100, item.step ?? 1);
+      break;
+    case "color":
+      controller = gui.addColor(obj, "value");
+      break;
+    case "boolean":
+      controller = gui.add(obj, "value");
+      break;
+    case "string":
+      controller = gui.add(obj, "value");
+      break;
+    case "dropdown":
+      controller = gui.add(obj, "value", item.options);
+      break;
+    default:
+      return;
+  }
+  controller.name(item.name);
+  controller.onChange((value) => {
+    item.onChange(value);
+  });
+}
+function GuiManager() {
+  const pathname = (0, import_navigation.usePathname)();
+  const visible = useGuiVisible();
+  const definitions = useGuiDefinitions();
+  const { getSetting, updateSetting } = useSettings();
+  const containerRef = React4.useRef(null);
+  const getSettingRef = React4.useRef(getSetting);
+  const updateSettingRef = React4.useRef(updateSetting);
+  React4.useEffect(() => {
+    getSettingRef.current = getSetting;
+    updateSettingRef.current = updateSetting;
+  }, [getSetting, updateSetting]);
+  React4.useEffect(() => {
+    if (!visible || !definitions.length) return;
+    const container = containerRef.current;
+    if (!container) return;
+    const get = (path) => getSettingRef.current(path);
+    const set = (path, value) => updateSettingRef.current(path, value);
+    const items = buildGuiItemsFromDefinitions(definitions, pathname, get, set);
+    if (items.length === 0) return;
+    const gui = new import_lil_gui.default({ container, title: "Settings", autoPlace: false });
+    for (const item of items) addItem(gui, item);
+    return () => gui.destroy();
+  }, [pathname, visible, definitions]);
+  if (!visible) return null;
+  return React4.createElement("div", {
+    ref: containerRef,
+    style: { position: "fixed", top: 16, right: 16, zIndex: 9999 }
+  });
+}
+
+// src/use-setting.ts
+var React5 = __toESM(require("react"));
+function useSetting(path, defaultOrOptions, onChange) {
+  const { getSetting } = useSettings();
+  const visible = useGuiVisible();
+  const getDef = useGetDefinition();
+  const options = defaultOrOptions != null && typeof defaultOrOptions === "object" && !Array.isArray(defaultOrOptions) && "default" in defaultOrOptions ? defaultOrOptions : { default: defaultOrOptions, onChange };
+  const defaultVal = options.default ?? getDef(path)?.default;
+  const onChangeFn = options.onChange ?? onChange;
+  const raw = getSetting(path);
+  const value = visible ? raw ?? defaultVal : void 0;
+  const prevRef = React5.useRef(value);
+  React5.useEffect(() => {
+    if (value === void 0) return;
+    if (value !== prevRef.current) {
+      prevRef.current = value;
+      onChangeFn?.(value);
+    } else {
+      prevRef.current = value;
+    }
+  }, [value, onChangeFn]);
+  return value;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GuiConfigProvider,
+  GuiManager,
+  GuiProvider,
+  SettingsProvider,
+  buildGuiItemsFromDefinitions,
+  getDefinition,
+  getDefinitionsForRoute,
+  matchRoute,
+  useGetDefinition,
+  useGuiDefinitions,
+  useGuiVisible,
+  useSetting,
+  useSettings
+});

package/dist/index.mjs

@@ -0,0 +1,251 @@
+"use client";
+
+// src/settings-context.tsx
+import * as React from "react";
+function getByPath(obj, path) {
+  const parts = path.split(".").filter(Boolean);
+  let current = obj;
+  for (const key of parts) {
+    if (current == null || typeof current !== "object" || Array.isArray(current)) return void 0;
+    current = current[key];
+  }
+  return current;
+}
+function setByPath(obj, path, value) {
+  const parts = path.split(".").filter(Boolean);
+  if (parts.length === 0) return obj;
+  const result = { ...obj };
+  let current = result;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i];
+    const next = current[key];
+    const nextObj = next != null && typeof next === "object" && !Array.isArray(next) ? { ...next } : {};
+    current[key] = nextObj;
+    current = nextObj;
+  }
+  current[parts[parts.length - 1]] = value;
+  return result;
+}
+var SettingsContext = React.createContext(null);
+function SettingsProvider({ children, initialSettings = {} }) {
+  const [settings, setSettings] = React.useState(() => {
+    const result = {};
+    for (const key in initialSettings) {
+      const group = initialSettings[key];
+      if (group !== void 0) result[key] = group;
+    }
+    return result;
+  });
+  const updateSetting = React.useCallback((path, value2) => {
+    setSettings((prev) => setByPath(prev, path, value2));
+  }, []);
+  const getSetting = React.useCallback(
+    (path) => getByPath(settings, path),
+    [settings]
+  );
+  const getGroup = React.useCallback((name) => settings[name] ?? {}, [settings]);
+  const value = React.useMemo(
+    () => ({ settings, updateSetting, getSetting, getGroup }),
+    [settings, updateSetting, getSetting, getGroup]
+  );
+  return React.createElement(SettingsContext.Provider, { value }, children);
+}
+function useSettings() {
+  const ctx = React.useContext(SettingsContext);
+  if (!ctx) throw new Error("useSettings must be used within SettingsProvider");
+  return ctx;
+}
+
+// src/config-context.tsx
+import * as React2 from "react";
+
+// src/routes.ts
+function matchRoute(pathname, route) {
+  if (route === "*") return true;
+  if (route.endsWith("/*")) {
+    const prefix = route.slice(0, -2);
+    return pathname.startsWith(prefix + "/");
+  }
+  return pathname === route;
+}
+function getDefinitionsForRoute(definitions, pathname) {
+  return definitions.filter((def) => {
+    const routes = def.routes;
+    if (!routes?.length) return true;
+    return routes.some((r) => matchRoute(pathname, r));
+  });
+}
+function flatten(items, acc = /* @__PURE__ */ new Map()) {
+  for (const d of items) {
+    if (d.type === "folder") flatten(d.children, acc);
+    else if (d.id != null) acc.set(d.id, d);
+  }
+  return acc;
+}
+function getDefinition(definitions, id) {
+  return flatten(definitions).get(id);
+}
+
+// src/config-context.tsx
+var DefinitionsContext = React2.createContext([]);
+function GuiConfigProvider({ definitions, children }) {
+  const value = React2.useMemo(() => definitions, [definitions]);
+  return React2.createElement(DefinitionsContext.Provider, { value }, children);
+}
+function useGuiDefinitions() {
+  return React2.useContext(DefinitionsContext);
+}
+function useGetDefinition() {
+  const definitions = useGuiDefinitions();
+  return React2.useCallback((id) => getDefinition(definitions, id), [definitions]);
+}
+
+// src/gui-provider.tsx
+import * as React3 from "react";
+var GuiVisibilityContext = React3.createContext(false);
+function GuiProvider({
+  children,
+  visible = true
+}) {
+  const value = React3.useMemo(() => !!visible, [visible]);
+  return React3.createElement(GuiVisibilityContext.Provider, { value }, children);
+}
+function useGuiVisible() {
+  return React3.useContext(GuiVisibilityContext);
+}
+
+// src/gui-manager.tsx
+import * as React4 from "react";
+import { usePathname } from "next/navigation";
+import GUI from "lil-gui";
+
+// src/builder.ts
+function buildGuiItemsFromDefinitions(definitions, pathname, getSetting, updateSetting) {
+  const forRoute = getDefinitionsForRoute(definitions, pathname);
+  return forRoute.map((def) => definitionToGuiItem(def, getSetting, updateSetting));
+}
+function definitionToGuiItem(def, getSetting, updateSetting) {
+  if (def.type === "folder") {
+    return {
+      type: "folder",
+      name: def.name,
+      children: def.children.map((c) => definitionToGuiItem(c, getSetting, updateSetting))
+    };
+  }
+  const value = getSetting(def.id) ?? def.default;
+  switch (def.type) {
+    case "color":
+      return { type: "color", id: def.id, name: def.name, value, onChange: (v) => updateSetting(def.id, v) };
+    case "number":
+      return { type: "number", id: def.id, name: def.name, value, min: def.min, max: def.max, step: def.step, onChange: (v) => updateSetting(def.id, v) };
+    case "boolean":
+      return { type: "boolean", id: def.id, name: def.name, value, onChange: (v) => updateSetting(def.id, v) };
+    case "string":
+      return { type: "string", id: def.id, name: def.name, value, onChange: (v) => updateSetting(def.id, v) };
+    case "dropdown":
+      return { type: "dropdown", id: def.id, name: def.name, value, options: def.options, onChange: (v) => updateSetting(def.id, v) };
+  }
+}
+
+// src/gui-manager.tsx
+function addItem(gui, item) {
+  if (item.type === "folder") {
+    const folder = gui.addFolder(item.name);
+    for (const child of item.children) addItem(folder, child);
+    return;
+  }
+  const obj = { value: item.value };
+  let controller;
+  switch (item.type) {
+    case "number":
+      controller = gui.add(obj, "value", item.min ?? 0, item.max ?? 100, item.step ?? 1);
+      break;
+    case "color":
+      controller = gui.addColor(obj, "value");
+      break;
+    case "boolean":
+      controller = gui.add(obj, "value");
+      break;
+    case "string":
+      controller = gui.add(obj, "value");
+      break;
+    case "dropdown":
+      controller = gui.add(obj, "value", item.options);
+      break;
+    default:
+      return;
+  }
+  controller.name(item.name);
+  controller.onChange((value) => {
+    item.onChange(value);
+  });
+}
+function GuiManager() {
+  const pathname = usePathname();
+  const visible = useGuiVisible();
+  const definitions = useGuiDefinitions();
+  const { getSetting, updateSetting } = useSettings();
+  const containerRef = React4.useRef(null);
+  const getSettingRef = React4.useRef(getSetting);
+  const updateSettingRef = React4.useRef(updateSetting);
+  React4.useEffect(() => {
+    getSettingRef.current = getSetting;
+    updateSettingRef.current = updateSetting;
+  }, [getSetting, updateSetting]);
+  React4.useEffect(() => {
+    if (!visible || !definitions.length) return;
+    const container = containerRef.current;
+    if (!container) return;
+    const get = (path) => getSettingRef.current(path);
+    const set = (path, value) => updateSettingRef.current(path, value);
+    const items = buildGuiItemsFromDefinitions(definitions, pathname, get, set);
+    if (items.length === 0) return;
+    const gui = new GUI({ container, title: "Settings", autoPlace: false });
+    for (const item of items) addItem(gui, item);
+    return () => gui.destroy();
+  }, [pathname, visible, definitions]);
+  if (!visible) return null;
+  return React4.createElement("div", {
+    ref: containerRef,
+    style: { position: "fixed", top: 16, right: 16, zIndex: 9999 }
+  });
+}
+
+// src/use-setting.ts
+import * as React5 from "react";
+function useSetting(path, defaultOrOptions, onChange) {
+  const { getSetting } = useSettings();
+  const visible = useGuiVisible();
+  const getDef = useGetDefinition();
+  const options = defaultOrOptions != null && typeof defaultOrOptions === "object" && !Array.isArray(defaultOrOptions) && "default" in defaultOrOptions ? defaultOrOptions : { default: defaultOrOptions, onChange };
+  const defaultVal = options.default ?? getDef(path)?.default;
+  const onChangeFn = options.onChange ?? onChange;
+  const raw = getSetting(path);
+  const value = visible ? raw ?? defaultVal : void 0;
+  const prevRef = React5.useRef(value);
+  React5.useEffect(() => {
+    if (value === void 0) return;
+    if (value !== prevRef.current) {
+      prevRef.current = value;
+      onChangeFn?.(value);
+    } else {
+      prevRef.current = value;
+    }
+  }, [value, onChangeFn]);
+  return value;
+}
+export {
+  GuiConfigProvider,
+  GuiManager,
+  GuiProvider,
+  SettingsProvider,
+  buildGuiItemsFromDefinitions,
+  getDefinition,
+  getDefinitionsForRoute,
+  matchRoute,
+  useGetDefinition,
+  useGuiDefinitions,
+  useGuiVisible,
+  useSetting,
+  useSettings
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@nonsoanetoh/lil-gui-helper",
+  "version": "0.1.0",
+  "description": "A Route-aware lil-gui manager for Next.js with a central config and useSetting hook",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "next": ">=14.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "lil-gui": "^0.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "next": ">=14.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "next",
+    "lil-gui",
+    "gui",
+    "settings",
+    "dev-tools"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nonsoanetoh/lil-gui-helper.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.tsx --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.tsx --format cjs,esm --dts --watch"
+  }
+}

package/readme.md

@@ -0,0 +1,156 @@
+# lil-gui-helper
+
+Route-aware [lil-gui](https://lil-gui.georgealways.com/) manager for Next.js App Router: central config, optional visibility flag, and `useSetting` hook.
+
+## Install
+
+From npm (when published):
+
+```bash
+pnpm add lil-gui-helper
+# or
+npm i lil-gui-helper
+```
+
+From a **private GitHub repo** (see [Publishing to a private repo](#publishing-to-a-private-repo) below):
+
+```bash
+pnpm add git+https://github.com/YOUR_USERNAME/lil-gui-helper.git
+# or with SSH
+pnpm add git+ssh://git@github.com:YOUR_USERNAME/lil-gui-helper.git
+```
+
+## Usage
+
+### 1. Define your config
+
+Create a config array (e.g. `lib/gui-config.ts`):
+
+```ts
+import type { SettingDefinitionItem } from "lil-gui-helper";
+
+export const GUI_DEFINITIONS: SettingDefinitionItem[] = [
+  {
+    id: "home.backgroundColor",
+    type: "color",
+    name: "Background Color",
+    default: "#fefefe",
+    routes: ["/"],
+  },
+  {
+    type: "folder",
+    name: "Position",
+    routes: ["/work/*"],
+    children: [
+      { id: "position.x", type: "number", name: "X", default: 0 },
+      { id: "position.y", type: "number", name: "Y", default: 0 },
+    ],
+  },
+];
+```
+
+**Routes:** `"*"` = all; `"/work"` = exact; `"/work/*"` = subroutes only (not `/work`).
+
+### 2. Wrap the app
+
+In your root layout (inside `body`):
+
+```tsx
+import {
+  SettingsProvider,
+  GuiConfigProvider,
+  GuiProvider,
+  GuiManager,
+} from "lil-gui-helper";
+import { GUI_DEFINITIONS } from "@/lib/gui-config";
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <SettingsProvider>
+          <GuiConfigProvider definitions={GUI_DEFINITIONS}>
+            <GuiProvider visible={process.env.NODE_ENV === "development"}>
+              {children}
+              <GuiManager />
+            </GuiProvider>
+          </GuiConfigProvider>
+        </SettingsProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+- **SettingsProvider** – stores values updated by the GUI.
+- **GuiConfigProvider** – provides your definitions (required for `GuiManager` and `useSetting` defaults).
+- **GuiProvider** – `visible`: when `false`, the panel is hidden and `useSetting` returns `undefined` so consumers use their default. Pass e.g. `visible={process.env.NODE_ENV === "development"}` to show only in dev.
+- **GuiManager** – builds and mounts the lil-gui panel from definitions + current pathname.
+
+### 3. Read values in pages
+
+```tsx
+"use client";
+
+import { useSetting } from "lil-gui-helper";
+
+export default function Home() {
+  const bg = useSetting("home.backgroundColor", "#fefefe");
+
+  return (
+    <div style={{ minHeight: "100vh", backgroundColor: bg ?? "#fefefe" }}>
+      …
+    </div>
+  );
+}
+```
+
+- `useSetting(path, default?)` – when GUI is visible returns the current value (or default); when hidden returns `undefined` so `value ?? default` uses your fallback.
+- `useSetting(path, { default, onChange })` – optional `onChange` when the value changes.
+
+## API
+
+| Export                                                                           | Description                                                                                          |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `SettingsProvider`                                                               | Holds settings state; required above GUI.                                                            |
+| `GuiConfigProvider`                                                              | Injects your `definitions`; required for `GuiManager` and definition-based defaults in `useSetting`. |
+| `GuiProvider`                                                                    | `visible` flag; when false, panel is hidden and `useSetting` is undefined.                           |
+| `GuiManager`                                                                     | Renders the lil-gui panel from definitions + pathname.                                               |
+| `useSetting(path, default?, onChange?)`                                         | Current value or undefined when GUI hidden.                                                         |
+| `useSettings()`                                                                  | Raw getSetting / updateSetting.                                                                      |
+| `matchRoute(pathname, route)`                                                    | `"*"` \| `"/path"` \| `"/path/*"`.                                                                   |
+| `getDefinitionsForRoute(definitions, pathname)`                                  | Filter definitions by pathname.                                                                      |
+| `getDefinition(definitions, id)`                                                 | Get leaf definition by id.                                                                           |
+| `buildGuiItemsFromDefinitions(definitions, pathname, getSetting, updateSetting)` | Build lil-gui items (for custom UIs).                                                               |
+
+## Publishing to a private repo
+
+### Option A: Private GitHub repository
+
+1. Create a **new private repo** on GitHub (e.g. `lil-gui-helper`).
+2. Update `package.json` in this package: set `repository.url` to your repo URL, e.g. `"url": "https://github.com/YOUR_USERNAME/lil-gui-helper.git"`.
+3. From this monorepo, copy only the package into the new repo (or push the whole `packages/lil-gui-helper` folder as the root of the new repo):
+   - Easiest: create the repo, then push the contents of `packages/lil-gui-helper` as the root (so the new repo has `package.json`, `src/`, `README.md`, etc. at top level).
+4. In the new repo, run `pnpm install` and `pnpm build`.
+5. In other projects, install from Git:
+   ```bash
+   pnpm add git+https://github.com/YOUR_USERNAME/lil-gui-helper.git
+   ```
+   For a private repo you’ll need auth (SSH key, or a personal access token in the URL, or `npm config set` for Git credentials).
+
+### Option B: Private npm package (scoped)
+
+1. Use a scoped name in `package.json`, e.g. `"name": "@your-npm-username/lil-gui-helper"`.
+2. Build: `cd packages/lil-gui-helper && pnpm build`.
+3. Publish as private (requires an npm paid plan for private packages):
+   ```bash
+   npm login
+   npm publish --access restricted
+   ```
+   Or with a scope that’s configured for private: `npm publish`.
+
+4. Install in other projects: `pnpm add @your-npm-username/lil-gui-helper`.
+
+---
+
+**Next step:** Open a new tab, create the private GitHub repo, then we can wire the `repository` URL and decide whether you’re using Option A (install from Git) or Option B (private npm).