@cosmicdrift/kumiko-renderer 0.347.0 → 0.348.1

package/dist/context/dispatcher-context.d.ts

@@ -1,10 +1,12 @@
 import type { Dispatcher, DispatcherStatus } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode } from "react";
+import { type QueryPools } from "./query-pool.js";
 export type DispatcherProviderProps = {
     readonly dispatcher: Dispatcher;
     readonly children: ReactNode;
 };
 export declare function DispatcherProvider({ dispatcher, children }: DispatcherProviderProps): ReactNode;
+export declare function useOptionalQueryPools(): QueryPools | undefined;
 export declare function useDispatcher(): Dispatcher;
 export declare function useOptionalDispatcher(): Dispatcher | undefined;
 export declare function useDispatcherStatus(): DispatcherStatus;

package/dist/context/dispatcher-context.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext } from "react";
+import { createContext, useContext, useState } from "react";
 import { useStore } from "../hooks/use-store.js";
+import { createQueryPools } from "./query-pool.js";
 // React Context threading the Dispatcher through the tree. An app
 // wraps its root in <DispatcherProvider dispatcher={createLiveDispatcher()}>
 // and every hook below reaches into that context instead of taking the
@@ -11,8 +12,14 @@ import { useStore } from "../hooks/use-store.js";
 // dispatcher per app (rebuilding would wipe its in-flight tracking and
 // status listeners). Tests wire a fake dispatcher in directly.
 const DispatcherContext = createContext(null);
+const QueryPoolsContext = createContext(null);
 export function DispatcherProvider({ dispatcher, children }) {
-    return _jsx(DispatcherContext, { value: dispatcher, children: children });
+    // Pools live with the provider so every hook of one query name shares them.
+    const [queryPools] = useState(createQueryPools);
+    return (_jsx(DispatcherContext, { value: dispatcher, children: _jsx(QueryPoolsContext, { value: queryPools, children: children }) }));
+}
+export function useOptionalQueryPools() {
+    return useContext(QueryPoolsContext) ?? undefined;
 }
 // Reads the ambient Dispatcher. Throws instead of returning null when
 // no provider is mounted — a dispatcher-less hook is always a

package/dist/context/query-pool.d.ts

@@ -0,0 +1,11 @@
+export type QuerySlot = {
+    readonly release: () => void;
+};
+export type QueryPools = {
+    /** Resolves with a slot once fewer than `limit` requests of this query name
+     *  run, or with null when `signal` aborts first (a waiter that gives up
+     *  never holds a slot). The caller must release a granted slot exactly once. Hooks of one
+     *  query name are expected to pass the same limit. */
+    readonly acquire: (name: string, limit: number, signal: AbortSignal) => Promise<QuerySlot | null>;
+};
+export declare function createQueryPools(): QueryPools;

package/dist/context/query-pool.js

@@ -0,0 +1,64 @@
+export function createQueryPools() {
+    const pools = new Map();
+    const poolFor = (name) => {
+        const existing = pools.get(name);
+        if (existing)
+            return existing;
+        const created = { running: 0, waiting: [] };
+        pools.set(name, created);
+        return created;
+    };
+    const makeSlot = (name, pool) => {
+        let released = false;
+        return {
+            release: () => {
+                if (!released) {
+                    released = true;
+                    pool.running -= 1;
+                    drain(name, pool);
+                }
+            },
+        };
+    };
+    const drain = (name, pool) => {
+        let next = pool.waiting[0];
+        while (next !== undefined && pool.running < next.limit) {
+            pool.waiting.shift();
+            pool.running += 1;
+            next.grant(makeSlot(name, pool));
+            next = pool.waiting[0];
+        }
+        if (pool.running === 0 && pool.waiting.length === 0)
+            pools.delete(name);
+    };
+    return {
+        acquire: (name, limit, signal) => {
+            if (signal.aborted)
+                return Promise.resolve(null);
+            const pool = poolFor(name);
+            if (pool.waiting.length === 0 && pool.running < limit) {
+                pool.running += 1;
+                return Promise.resolve(makeSlot(name, pool));
+            }
+            return new Promise((resolve) => {
+                const waiter = {
+                    limit,
+                    grant: (slot) => {
+                        signal.removeEventListener("abort", onAbort);
+                        resolve(slot);
+                    },
+                };
+                const onAbort = () => {
+                    const index = pool.waiting.indexOf(waiter);
+                    if (index >= 0)
+                        pool.waiting.splice(index, 1);
+                    signal.removeEventListener("abort", onAbort);
+                    resolve(null);
+                    drain(name, pool);
+                };
+                signal.addEventListener("abort", onAbort);
+                pool.waiting.push(waiter);
+            });
+        },
+    };
+}

package/dist/hooks/use-query.d.ts

@@ -9,6 +9,7 @@ export type UseQueryOptions = {
     readonly enabled?: boolean;
     readonly live?: boolean;
     readonly refetchIntervalMs?: number;
+    readonly concurrency?: number;
 };
 export declare function entityFromQueryType(type: string): string | undefined;
 export declare function useQuery<TData = unknown>(type: string, payload: unknown, options?: UseQueryOptions): UseQueryResult<TData>;

package/dist/hooks/use-query.js

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from "react";
-import { useDispatcher } from "../context/dispatcher-context.js";
+import { useDispatcher, useOptionalQueryPools } from "../context/dispatcher-context.js";
 import { useLiveEvents } from "../sse/live-events.js";
 // Extract the entity-name from a standard Kumiko query type. Returns
 // undefined for non-conforming types so the live-mode silently skips
@@ -13,9 +13,13 @@ export function entityFromQueryType(type) {
         return undefined;
     return parts[2];
 }
+function isValidConcurrency(value) {
+    return value !== undefined && Number.isFinite(value) && value >= 1;
+}
 export function useQuery(type, payload, options = {}) {
     const dispatcher = useDispatcher();
-    const { enabled = true, live = false, refetchIntervalMs } = options;
+    const { enabled = true, live = false, refetchIntervalMs, concurrency } = options;
+    const queryPools = useOptionalQueryPools();
     const [data, setData] = useState(null);
     const [error, setError] = useState(null);
     const [loading, setLoading] = useState(enabled);
@@ -45,10 +49,21 @@ export function useQuery(type, payload, options = {}) {
         if (!background)
             setLoading(true);
         let result;
+        let slot = null;
         try {
+            if (queryPools !== undefined && isValidConcurrency(concurrency)) {
+                slot = await queryPools.acquire(type, Math.floor(concurrency), ctrl.signal);
+                // skip: aborted while queued, the superseding run owns the state
+                if (slot === null)
+                    return;
+                // skip: slot granted just as the run was superseded, finally frees it
+                if (ctrl.signal.aborted)
+                    return;
+            }
             result = await dispatcher.query(type, payload, { signal: ctrl.signal });
         }
         finally {
+            slot?.release();
             // A rejected fetch must not leave polling stuck; a superseded one must
             // not clear the newer fetch's flag.
             if (activeCtrl.current === ctrl)
@@ -69,7 +84,7 @@ export function useQuery(type, payload, options = {}) {
             setError(result.error);
         }
         setLoading(false);
-    }, [dispatcher, type, payloadKey]);
+    }, [dispatcher, type, payloadKey, queryPools, concurrency]);
     const run = useCallback(() => runFetch(false), [runFetch]);
     useEffect(() => {
         if (!enabled) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.347.0",
+  "version": "0.348.1",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,9 +15,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.347.0",
-    "@cosmicdrift/kumiko-headless": "0.347.0",
-    "@cosmicdrift/kumiko-types": "0.347.0",
+    "@cosmicdrift/kumiko-framework": "0.348.1",
+    "@cosmicdrift/kumiko-headless": "0.348.1",
+    "@cosmicdrift/kumiko-types": "0.348.1",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -28,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.347.0"
+    "@cosmicdrift/kumiko-locale-de": "0.348.1"
   },
   "repository": {
     "type": "git",

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.348.0",
+    "type": "improvement",
+    "title": "ModeSwitch gains a pill variant and className, LanguageSwitcher gains a compact chip variant",
+    "detail": "ModeSwitch pill variant and LanguageSwitcher chip variant\n`ModeSwitch` gets `variant=\"pill\"` (grey track, raised active segment, dark mode aware) and a `className` prop; `outline` stays the default. `LanguageSwitcher` gets `variant=\"chip\"`, a compact monospace chip with the uppercase locale code in a border; `default` stays as it was."
+  },
+  {
+    "version": "0.348.0",
+    "type": "improvement",
+    "title": "TimeseriesChart takes a height, an optional y-axis with gridlines and a date axis with n labels",
+    "detail": "TimeseriesChart: height, y-axis gridlines and a date axis\n`height` (px) replaces the fixed `h-16`; without it the chart looks as before. `yAxis: { ticks, format? }` draws that many gridlines with rounded value labels (0/200/400/600) in a left gutter, and the y-scale reaches the top tick. `xAxis: { ticks, format }` renders n evenly spaced date labels instead of the fixed start/mid/end of `axisLabels`."
+  },
+  {
+    "version": "0.348.0",
+    "type": "improvement",
+    "title": "useQuery accepts concurrency to cap parallel requests per query name through a pool in the DispatcherProvider",
+    "detail": "useQuery option `concurrency` caps parallel requests per query name\n`useQuery(type, payload, { concurrency: n })` lets at most n `dispatcher.query` calls of that query name run at once. The pool lives in the DispatcherProvider and is shared by every hook with the same name; the rest wait in line with `loading` still true. A hook that unmounts, refetches or changes its payload while waiting leaves the line without holding a slot, and a finished or failed request hands its slot to the next waiter. Without the option nothing changes."
+  },
   {
     "version": "0.347.0",
     "type": "improvement",