zudoku 0.0.0-z7b86faab → 0.0.0-z8ac421f0

package/src/lib/components/navigation/utils.ts

@@ -86,6 +86,13 @@ export const usePrevNext = (): {
   let foundCurrent = false;
 
   traverseNavigation(navigation, (item) => {
+    if (
+      item.type === "separator" ||
+      item.type === "section" ||
+      item.type === "filter"
+    )
+      return;
+
     const itemId =
       item.type === "doc"
         ? joinUrl(item.path)
@@ -133,9 +140,33 @@ export const navigationListItem = cva(
   },
 );
 
+export const itemMatchesFilter = (
+  item: NavigationItem,
+  query: string,
+): boolean => {
+  if (["separator", "section", "filter"].includes(item.type)) {
+    return true;
+  }
+  if (item.label?.toLowerCase().includes(query.toLowerCase())) {
+    return true;
+  }
+
+  if (item.type === "category") {
+    return item.items.some((child) => itemMatchesFilter(child, query));
+  }
+
+  return false;
+};
+
 export const shouldShowItem =
-  (auth: UseAuthReturn, context: ZudokuContext) =>
+  (auth: UseAuthReturn, context: ZudokuContext, filterQuery?: string) =>
   (item: NavigationItem): boolean => {
+    if (item.type === "filter") return true;
+
+    if (filterQuery?.trim() && !itemMatchesFilter(item, filterQuery)) {
+      return false;
+    }
+
     if (typeof item.display === "function") {
       return item.display({ context, auth });
     }

package/src/lib/core/ZudokuContext.ts

@@ -132,10 +132,15 @@ export class ZudokuContext {
   public readonly getAuthState: () => AuthState;
   public readonly queryClient: QueryClient;
   public readonly options: ZudokuContextOptions;
+  public readonly env: Record<string, string | undefined>;
   private readonly navigationPlugins: NavigationPlugin[];
   private emitter = createNanoEvents<ZudokuEvents>();
 
-  constructor(options: ZudokuContextOptions, queryClient: QueryClient) {
+  constructor(
+    options: ZudokuContextOptions,
+    queryClient: QueryClient,
+    env: Record<string, string | undefined>,
+  ) {
     const pluginProtectedRoutes = Object.fromEntries(
       (options.plugins ?? []).flatMap((plugin) => {
         if (!isNavigationPlugin(plugin)) return [];
@@ -152,6 +157,7 @@ export class ZudokuContext {
     };
 
     this.queryClient = queryClient;
+    this.env = env;
     this.options = { ...options, protectedRoutes };
     this.plugins = options.plugins ?? [];
     this.navigation = options.navigation ?? [];

package/src/lib/core/__internal.tsx

@@ -17,6 +17,7 @@ import { StatusPage as StatusPageImport } from "../components/StatusPage.js";
 import { RouterError as RouterErrorImport } from "../errors/RouterError.js";
 import { ServerError as ServerErrorImport } from "../errors/ServerError.js";
 import { RouteGuard as RouteGuardImport } from "./RouteGuard.js";
+import { runPluginTransformConfig as runPluginTransformConfigImport } from "./transform-config.js";
 
 export const Layout = LayoutImport;
 export const RouterError = RouterErrorImport;
@@ -28,3 +29,4 @@ export const Head = Helmet;
 export const StatusPage = StatusPageImport;
 export const BuildCheck = BuildCheckImport;
 export const Meta = MetaImport;
+export const runPluginTransformConfig = runPluginTransformConfigImport;

package/src/lib/core/plugins.ts

@@ -68,11 +68,15 @@ export interface ConfigHookContext {
   configPath: string;
 }
 
+export interface TransformConfigContext {
+  config: ZudokuConfig;
+  merge: <T extends Partial<ZudokuConfig>>(partial: T) => ZudokuConfig & T;
+}
+
 export interface TransformConfigPlugin {
   transformConfig?: (
-    config: ZudokuConfig,
-    ctx: ConfigHookContext,
-  ) => Partial<ZudokuConfig> | void | Promise<Partial<ZudokuConfig> | void>;
+    context: TransformConfigContext,
+  ) => ZudokuConfig | void | Promise<ZudokuConfig | void>;
 }
 
 export interface CommonPlugin {

package/src/lib/core/transform-config.test.tsx

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "vitest";
+import { isPlainObject, mergeConfig } from "./transform-config.js";
+
+describe("isPlainObject", () => {
+  test("returns true for plain objects", () => {
+    expect(isPlainObject({})).toBe(true);
+    expect(isPlainObject({ a: 1 })).toBe(true);
+  });
+
+  test("returns false for arrays", () => {
+    expect(isPlainObject([])).toBe(false);
+    expect(isPlainObject([1, 2, 3])).toBe(false);
+  });
+
+  test("returns false for null and undefined", () => {
+    expect(isPlainObject(null)).toBe(false);
+    expect(isPlainObject(undefined)).toBe(false);
+  });
+
+  test("returns false for class instances", () => {
+    expect(isPlainObject(new Date())).toBe(false);
+    expect(isPlainObject(new Map())).toBe(false);
+    expect(isPlainObject(/regex/)).toBe(false);
+  });
+});
+
+describe("mergeConfig", () => {
+  test("merges flat objects", () => {
+    const target = { a: 1, b: 2 };
+    const source = { b: 3, c: 4 };
+    expect(mergeConfig(target, source)).toEqual({ a: 1, b: 3, c: 4 });
+  });
+
+  test("merges nested objects", () => {
+    const target = { nested: { a: 1, b: 2 } } as Record<string, unknown>;
+    const source = { nested: { b: 3, c: 4 } };
+    expect(mergeConfig(target, source)).toEqual({
+      nested: { a: 1, b: 3, c: 4 },
+    });
+  });
+
+  test("replaces arrays instead of merging", () => {
+    const target = { arr: [1, 2, 3] };
+    const source = { arr: [4, 5] };
+    expect(mergeConfig(target, source)).toEqual({ arr: [4, 5] });
+  });
+
+  test("preserves React elements without deep cloning", () => {
+    const element = <div className="test">Hello</div>;
+    const target = { banner: { message: "old" } };
+    const source = { banner: { message: element } };
+
+    const result = mergeConfig(target, source);
+
+    // Should be the exact same reference, not a clone
+    expect(result.banner.message).toBe(element);
+  });
+
+  test("does not clone React element children", () => {
+    const child = <strong>Bold</strong>;
+    const element = <div>{child} text</div>;
+    const target = { site: { banner: {} } };
+    const source = { site: { banner: { message: element } } };
+
+    const result = mergeConfig(target, source);
+
+    // The element should be identical (same reference)
+    expect(result.site.banner.message).toBe(element);
+    // Children should be preserved exactly
+    expect(result.site.banner.message.props.children).toBe(
+      element.props.children,
+    );
+  });
+
+  test("handles null and undefined values", () => {
+    const target = { a: 1, b: 2 };
+    const source = { a: null, c: undefined };
+    expect(mergeConfig(target, source)).toEqual({
+      a: null,
+      b: 2,
+      c: undefined,
+    });
+  });
+
+  test("replaces non-plain objects", () => {
+    const date = new Date("2024-01-01");
+    const target = { date: new Date("2020-01-01") };
+    const source = { date };
+    const result = mergeConfig(target, source);
+    expect(result.date).toBe(date);
+  });
+
+  test("does not mutate target", () => {
+    const target = { a: 1, nested: { b: 2 } };
+    const source = { a: 2, nested: { c: 3 } };
+    mergeConfig(target, source);
+    expect(target).toEqual({ a: 1, nested: { b: 2 } });
+  });
+});

package/src/lib/core/transform-config.ts

@@ -1,28 +1,66 @@
-import createDeepmerge from "@fastify/deepmerge";
-import type { ConfigWithMeta } from "../../config/loader.js";
-import { type ConfigHookContext, isTransformConfigPlugin } from "./plugins.js";
-
-const mergeConfig = createDeepmerge({
-  mergeArray: (opt) => (_, source) => opt.clone(source),
-});
-
-export const runTransformConfigHooks = async (
-  config: ConfigWithMeta,
-): Promise<ConfigWithMeta> => {
-  const ctx = {
-    mode: config.__meta.mode,
-    rootDir: config.__meta.rootDir,
-    configPath: config.__meta.configPath,
-  } satisfies ConfigHookContext;
+import { isValidElement } from "react";
+import type { ZudokuConfig } from "../../config/validators/validate.js";
+import { isTransformConfigPlugin } from "./plugins.js";
+
+export const isPlainObject = (
+  value: unknown,
+): value is Record<string, unknown> =>
+  typeof value === "object" &&
+  value !== null &&
+  !Array.isArray(value) &&
+  Object.getPrototypeOf(value) === Object.prototype;
+
+export const mergeConfig = <
+  T extends Record<string, unknown>,
+  S extends Record<string, unknown>,
+>(
+  target: T,
+  source: S,
+): T & S => {
+  const result = { ...target } as T & S;
+
+  for (const key of Object.keys(source) as (keyof S)[]) {
+    const sourceValue = source[key];
+    const targetValue = target[key as keyof T];
+
+    // Don't merge React elements, arrays, or non-plain objects - just replace
+    if (
+      isValidElement(sourceValue) ||
+      Array.isArray(sourceValue) ||
+      !isPlainObject(sourceValue)
+    ) {
+      (result as Record<string, unknown>)[key as string] = sourceValue;
+    } else if (isPlainObject(targetValue)) {
+      (result as Record<string, unknown>)[key as string] = mergeConfig(
+        targetValue,
+        sourceValue,
+      );
+    } else {
+      (result as Record<string, unknown>)[key as string] = sourceValue;
+    }
+  }
+
+  return result;
+};
+
+export const runPluginTransformConfig = async <T extends ZudokuConfig>(
+  config: T,
+): Promise<T> => {
   const plugins = config.plugins ?? [];
 
   let result = config;
 
   for (const plugin of plugins.filter(isTransformConfigPlugin)) {
-    const partial = await plugin.transformConfig?.(result, ctx);
-    if (!partial) continue;
+    const merge = <T extends Record<string, unknown>>(partial: T) =>
+      mergeConfig(result, partial);
+
+    const transformed = await plugin.transformConfig?.({
+      config: result,
+      merge,
+    });
+    if (!transformed) continue;
 
-    result = mergeConfig(result, partial) as ConfigWithMeta;
+    result = transformed as T;
   }
 
   return result;

package/src/lib/errors/ErrorAlert.tsx

@@ -1,4 +1,3 @@
-import { SyntaxHighlight } from "zudoku/ui/SyntaxHighlight.js";
 import { DeveloperHint } from "../components/DeveloperHint.js";
 import { Heading } from "../components/Heading.js";
 import { Typography } from "../components/Typography.js";
@@ -22,11 +21,7 @@ export function ErrorAlert({ error }: { error: unknown }) {
       Error: {message}
       {hint && <DeveloperHint className="mb-4">{hint}</DeveloperHint>}
       {stringError && (
-        <SyntaxHighlight
-          className="max-h-[400px] [&>pre]:p-4"
-          language="js"
-          code={stringError}
-        />
+        <pre className="max-h-[400px] [&>pre]:p-4">{stringError}</pre>
       )}
     </Typography>
   );

package/src/lib/hooks/index.ts

@@ -1,16 +1,7 @@
-import { useMDXComponents as useMDXComponentsImport } from "@mdx-js/react";
-import { useTheme as useThemeImport } from "next-themes";
-import { useAuth as useAuthImport } from "../authentication/hook.js";
-import { CACHE_KEYS, useCache as useCacheImport } from "../components/cache.js";
-import { useZudoku as useZudokuImport } from "../components/context/ZudokuContext.js";
-import { useExposedProps as useExposedPropsImport } from "../util/useExposedProps.js";
-import { useEvent as useEventImport } from "./useEvent.js";
-
-export const useEvent = /*@__PURE__*/ useEventImport;
-export const useTheme = /*@__PURE__*/ useThemeImport;
-export const useExposedProps = /*@__PURE__*/ useExposedPropsImport;
-export const useMDXComponents = /*@__PURE__*/ useMDXComponentsImport;
-export const useAuth = /*@__PURE__*/ useAuthImport;
-export const useZudoku = /*@__PURE__*/ useZudokuImport;
-export const useCache = /*@__PURE__*/ useCacheImport;
-export { CACHE_KEYS };
+export { useMDXComponents } from "@mdx-js/react";
+export { useTheme } from "next-themes";
+export { useAuth } from "../authentication/hook.js";
+export { CACHE_KEYS, useCache } from "../components/cache.js";
+export { useZudoku } from "../components/context/ZudokuContext.js";
+export { useExposedProps } from "../util/useExposedProps.js";
+export { useEvent } from "./useEvent.js";

package/src/lib/hooks/useEvent.test.tsx

@@ -13,7 +13,7 @@ import { useEvent } from "./useEvent.js";
 
 const createTestContext = () => {
   const queryClient = new QueryClient();
-  const context = new ZudokuContext({}, queryClient);
+  const context = new ZudokuContext({}, queryClient, {});
   const wrapper = ({ children }: PropsWithChildren) => (
     <QueryClientProvider client={queryClient}>
       <ZudokuProvider context={context}>{children}</ZudokuProvider>

package/src/lib/oas/graphql/circular.test.ts

@@ -156,16 +156,20 @@ describe("handleCircularRefs", () => {
     });
   });
 
-  it("should deduplicate shared object instances with __$ref", () => {
+  it("should handle shared object instances with __$ref without marking circular", () => {
     const shared = { __$ref: "#/components/schemas/Foo", type: "string" };
     const obj = { a: shared, b: shared };
     const result = handleCircularRefs(obj);
 
+    // Both should return the cached result, not mark as circular
     expect(result.a).toEqual({
       __$ref: "#/components/schemas/Foo",
       type: "string",
     });
-    expect(result.b).toBe(`${SCHEMA_REF_PREFIX}#/components/schemas/Foo`);
+    expect(result.b).toEqual({
+      __$ref: "#/components/schemas/Foo",
+      type: "string",
+    });
   });
 
   it("should mark circular ref with property name from path", () => {
@@ -183,4 +187,35 @@ describe("handleCircularRefs", () => {
 
     expect(result.properties.child.properties.back).toContain(CIRCULAR_REF);
   });
+
+  // Exact reproduction of #1869 - shared object instances with __$ref
+  it("should NOT mark shared object instances with __$ref as circular (issue #1869)", () => {
+    // When dereferencing, the SAME object instance is returned for all refs to the same schema
+    const timestampSchema = {
+      __$ref: "#/components/schemas/timestamp",
+      type: "string",
+      format: "date-time",
+    };
+
+    // Both created_at and updated_at point to the SAME object instance
+    const obj = {
+      type: "object",
+      properties: {
+        created_at: timestampSchema,
+        updated_at: timestampSchema,
+      },
+    };
+
+    const result = handleCircularRefs(obj);
+
+    // The first one should be fully expanded
+    expect(result.properties.created_at).toEqual({
+      __$ref: "#/components/schemas/timestamp",
+      type: "string",
+      format: "date-time",
+    });
+    // The second one should ALSO be fully expanded (not marked as circular)
+    expect(typeof result.properties.updated_at).toBe("object");
+    expect(result.properties.updated_at).not.toContain(CIRCULAR_REF);
+  });
 });

package/src/lib/oas/graphql/circular.ts

@@ -1,6 +1,5 @@
 import { GraphQLScalarType } from "graphql/index.js";
 import { GraphQLJSON } from "graphql-type-json";
-import type { RecordAny } from "../../util/traverse.js";
 
 export const CIRCULAR_REF = "$[Circular Reference]";
 export const SCHEMA_REF_PREFIX = "$ref:";
@@ -17,73 +16,48 @@ const OPENAPI_PROPS = new Set([
 export const handleCircularRefs = (
   // biome-ignore lint/suspicious/noExplicitAny: Allow any type
   obj: any,
-  visited = new WeakSet(),
+  currentPath = new WeakSet(),
   refs = new WeakMap(),
   path: string[] = [],
-  seenRefPaths = new Set<string>(),
+  currentRefPaths = new Set<string>(),
   // biome-ignore lint/suspicious/noExplicitAny: Allow any type
 ): any => {
   if (obj === null || typeof obj !== "object") return obj;
 
   const refPath = obj.__$ref;
+  const isCircular =
+    currentPath.has(obj) ||
+    (typeof refPath === "string" && currentRefPaths.has(refPath));
 
-  // Check if this object has a __$ref marker (set during schema code generation)
-  // If we've already fully processed this ref path, return a reference marker
-  // instead of the full data to avoid JSON.stringify serializing duplicates
-  if (typeof refPath === "string" && seenRefPaths.has(refPath)) {
-    return SCHEMA_REF_PREFIX + refPath;
-  }
-
-  if (visited.has(obj)) {
-    const cached = refs.get(obj);
-    if (cached) {
-      return typeof refPath === "string"
-        ? // If already processed, return ref marker to avoid duplicate serialization
-          SCHEMA_REF_PREFIX + refPath
-        : cached;
-    }
+  if (isCircular) {
+    if (typeof refPath === "string") return SCHEMA_REF_PREFIX + refPath;
     const circularProp = path.find((p) => !OPENAPI_PROPS.has(p)) || path[0];
-
     return [CIRCULAR_REF, circularProp].filter(Boolean).join(":");
   }
 
-  visited.add(obj);
+  if (refs.has(obj)) return refs.get(obj);
 
-  // Add refPath BEFORE recursing to detect cycles within this branch
-  // This will be removed after processing to allow siblings with the same ref
-  if (typeof refPath === "string") {
-    seenRefPaths.add(refPath);
-  }
+  currentPath.add(obj);
+  if (typeof refPath === "string") currentRefPaths.add(refPath);
 
-  let result: RecordAny | RecordAny[];
-  if (Array.isArray(obj)) {
-    result = obj.map((item, index) =>
-      handleCircularRefs(
-        item,
-        visited,
-        refs,
-        [...path, index.toString()],
-        seenRefPaths,
-      ),
+  const recurse = (value: unknown, key: string) =>
+    handleCircularRefs(
+      value,
+      currentPath,
+      refs,
+      [...path, key],
+      currentRefPaths,
     );
-  } else {
-    result = {};
-    for (const [key, value] of Object.entries(obj)) {
-      result[key] = handleCircularRefs(
-        value,
-        visited,
-        refs,
-        [...path, key],
-        seenRefPaths,
+
+  const result = Array.isArray(obj)
+    ? obj.map((item, i) => recurse(item, i.toString()))
+    : Object.fromEntries(
+        Object.entries(obj).map(([k, v]) => [k, recurse(v, k)]),
       );
-    }
-  }
-  refs.set(obj, result);
 
-  // Remove refPath after processing so sibling refs aren't incorrectly marked
-  if (typeof refPath === "string") {
-    seenRefPaths.delete(refPath);
-  }
+  refs.set(obj, result);
+  currentPath.delete(obj);
+  if (typeof refPath === "string") currentRefPaths.delete(refPath);
 
   return result;
 };

package/src/lib/oas/parser/index.ts

@@ -1,6 +1,7 @@
 import { GraphQLError } from "graphql/error/index.js";
 import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
-import { flattenAllOfProcessor } from "../../util/flattenAllOf.js";
+import { flattenAllOf } from "../../util/flattenAllOf.js";
+import { traverse } from "../../util/traverse.js";
 import { dereference, type JSONSchema } from "./dereference/index.js";
 import { upgradeSchema } from "./upgrade/index.js";
 
@@ -104,11 +105,21 @@ export const validate = async (schemaInput: unknown) => {
   const dereferenced = await dereference(schema);
   const upgraded = upgradeSchema(dereferenced);
 
-  const flattened = await flattenAllOfProcessor({
-    schema: upgraded,
-    file: "schema.json",
-    dereference: async (schema) => schema,
-  });
+  const flattened = traverse(upgraded, (spec) => {
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+      return spec;
+    }
+    const isSchemaObject =
+      "type" in spec ||
+      "properties" in spec ||
+      "allOf" in spec ||
+      "anyOf" in spec ||
+      "oneOf" in spec;
+
+    if (!isSchemaObject) return spec;
+
+    return flattenAllOf(spec) as typeof spec;
+  }) as OpenAPIDocument;
 
   return flattened;
 };

package/src/lib/plugins/openapi/ParamInfos.tsx

@@ -28,11 +28,16 @@ const Pattern = ({ pattern }: { pattern: string }) => {
 const getSchemaInfos = (schema?: SchemaObject) => {
   if (!schema) return [];
 
+  const items =
+    schema.type === "array" && typeof schema.items === "object"
+      ? schema.items
+      : undefined;
+
   return [
-    schema.type === "array" && schema.items.type
-      ? Array.isArray(schema.items.type)
-        ? `(${schema.items.type.join(" | ")})[]`
-        : `${schema.items.type}[]`
+    items?.type
+      ? Array.isArray(items.type)
+        ? `(${items.type.join(" | ")})[]`
+        : `${items.type}[]`
       : Array.isArray(schema.type)
         ? schema.type.join(" | ")
         : schema.type,
@@ -40,7 +45,7 @@ const getSchemaInfos = (schema?: SchemaObject) => {
     schema.enum && "enum",
     schema.const && "const",
     schema.format,
-    schema.type === "array" && schema.items?.contentMediaType,
+    items?.contentMediaType,
     schema.minimum !== undefined && `min: ${schema.minimum}`,
     schema.maximum !== undefined && `max: ${schema.maximum}`,
     schema.minLength !== undefined && `minLength: ${schema.minLength}`,

package/src/lib/plugins/openapi/ParameterListItem.tsx

@@ -90,6 +90,7 @@ export const ParameterListItem = ({
               </code>
             )}
           </ItemTitle>
+          {"\u200B"}
           <ParamInfos
             className="inline"
             schema={paramSchema}

package/src/lib/plugins/openapi/playground/fileUtils.ts

@@ -4,6 +4,10 @@ export function isBinaryContentType(contentType: string) {
   );
 }
 
+export function isAudioContentType(contentType: string) {
+  return /^audio\//i.test(contentType);
+}
+
 export const extractFileName = (
   headers: Array<[string, string]>,
   url: string,

package/src/lib/plugins/openapi/playground/result-panel/AudioPlayer.tsx

@@ -0,0 +1,50 @@
+import { DownloadIcon } from "lucide-react";
+import { useEffect, useState } from "react";
+import { Button } from "zudoku/ui/Button.js";
+import { humanFileSize } from "../../../../util/humanFileSize.js";
+
+export const AudioPlayer = ({
+  blob,
+  fileName,
+  size,
+  onDownload,
+}: {
+  blob: Blob;
+  fileName: string;
+  size: number;
+  onDownload: () => void;
+}) => {
+  const [audioUrl, setAudioUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    const url = URL.createObjectURL(blob);
+    setAudioUrl(url);
+
+    return () => {
+      URL.revokeObjectURL(url);
+    };
+  }, [blob]);
+
+  if (!audioUrl) {
+    return (
+      <div className="p-4 text-center">
+        <div className="text-sm text-muted-foreground">Loading audio...</div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-4 text-center">
+      <div className="flex flex-col items-center gap-4">
+        {/* biome-ignore lint/a11y/useMediaCaption: API response audio cannot have predefined captions */}
+        <audio controls src={audioUrl} className="w-full max-w-md">
+          Your browser does not support the audio element.
+        </audio>
+        <Button onClick={onDownload} className="flex items-center gap-2">
+          <DownloadIcon className="h-4 w-4" />
+          Download {fileName} ({humanFileSize(size)})
+        </Button>
+      </div>
+    </div>
+  );
+};