@owlmeans/api-config-client 0.1.18-rc.12 → 0.1.18-rc.13

package/README.md

@@ -11,7 +11,7 @@ Client-side middleware that fetches server config from `GET /assets/config.json`
 ## Installation
 
 ```bash
-bun add @owlmeans/api-config-client
+bun add @owlmeans/api-config-client@^0.1.18-rc.12
 ```
 
 ## Usage
@@ -45,7 +45,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.12
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/api-config-client",
-  "version": "0.1.18-rc.12",
-  "generatedAt": "2026-09-01T17:39:40.765Z",
+  "version": "0.1.18-rc.13",
+  "generatedAt": "2026-09-04T22:43:25.446Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/api-config-client/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-config-client
-description: How to use @owlmeans/api-config-client — client-side middleware and modules for fetching the API config served by api-config-server. Auto-invoked when wiring runtime API config into a client app.
+description: How to use @owlmeans/api-config-client — the browser half of the runtime config flow, a loading-stage middleware that fetches the config a backend advertises and merges it into the client config. Auto-invoked when wiring runtime API config into a client app or debugging a client that boots with an incomplete config.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,22 +8,71 @@ user-invocable: false
 # @owlmeans/api-config-client
 
 **Layer:** Client
-**Install:** `"@owlmeans/api-config-client": "^0.1.18-rc.12"` in `dependencies`
+**Install:** `"@owlmeans/api-config-client": "^0.1.18-rc.13"` in `dependencies`
+
+Consumes the declaration shared by `@owlmeans/api-config` and answered by
+`@owlmeans/api-config-server`.
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `apiConfigMiddleware` | Middleware to fetch and apply remote API config at startup |
-| `modules` | Client-side api-config module declarations |
+| `apiConfigMiddleware` | Context middleware, `Loading` stage — fetches the advertised config and merges it into `context.cfg` |
+| `entrypoints` | The `API_CONFIG` declaration elevated for client use, so the middleware can call it |
 
 ## Usage
 
+Both halves are needed: the middleware does the work, the entrypoint is what it calls.
+
 ```typescript
-import { modules as apiConfigClientModules } from '@owlmeans/api-config-client'
-context.registerEntrypoints([...apiConfigClientModules, ...appModules])
+import { apiConfigMiddleware, entrypoints as apiConfigEntrypoints } from '@owlmeans/api-config-client'
+
+export const makeContext = <C extends AppConfig, T extends AppContext<C>>(cfg: C): T => {
+  const context = makeClientContext(cfg) as T
+  context.registerMiddleware(apiConfigMiddleware)
+  return context
+}
+
+export const appEntrypoints = [...apiConfigEntrypoints, ...myEntrypoints]
 ```
 
+A panel app on `@owlmeans/web-panel` or `@owlmeans/mui-panel` already registers both — do it again
+only in a context built from a lower layer.
+
+## What the middleware does
+
+It runs once during `init()`, as a `Context`/`Loading` middleware — after every service and
+resource has initialized and just before the context is marked ready. So the merged values are
+there for anything that reads `cfg` at request or render time, but **not** for a value a service
+captured while initializing: that one still holds what the bundle shipped.
+
+- **Both halves, or the boot dies.** The middleware resolves `API_CONFIG` against the context
+  before it tests anything else, so a context that registers `apiConfigMiddleware` without also
+  spreading `entrypoints` fails `init()` with `SyntaxError: Entrypoint api-config:advertise not
+  found`. That failure is outside the swallowing below — it is a hard boot error, not a missing
+  value discovered later.
+- **It is a no-op unless `cfg.primaryHost` is set.** A build without it keeps whatever the bundle
+  was compiled with, silently. That is the first thing to check when a client boots with a config
+  the backend does not agree with.
+- `cfg.primaryHost` (and `cfg.primaryPort`, when given) are written onto the entrypoint's route
+  before the call, so the config is fetched from the primary backend rather than from wherever the
+  entrypoint would otherwise resolve.
+- The answer is merged into `context.cfg` in place by `mergeConfig` from `@owlmeans/config`:
+  objects are merged key by key, two arrays are **appended**, and the server's value replaces the
+  built-in one only where that built-in is a scalar, `null` or absent. Where the built-in is an
+  object or an array and the server sends a scalar, the merge recurses into that pair, matches
+  neither branch and returns the built-in untouched — **the server's value is silently dropped**.
+  An array the bundle already carries therefore grows on every merge, and can be neither replaced
+  nor emptied from the server.
+- A failed **fetch** is logged and swallowed — only the call and the merge are inside the
+  try/catch. The app continues on its built-in config, so a misconfigured or unreachable primary
+  host shows up as missing values later, never as a boot error.
+
 ## Depends On
 
-- `@owlmeans/api-config`, `@owlmeans/client-entrypoint`, `@owlmeans/client-context`
+Declared: `@owlmeans/api-config`, `@owlmeans/client-entrypoint`, `@owlmeans/client-context`,
+`@owlmeans/context`.
+
+Imported but **not** declared in this package's manifest: `@owlmeans/config` (`mergeConfig`, which
+does the merging described above). A workspace resolves it anyway; a standalone install has to name
+it in its own dependencies.

package/build/entrypoints.d.ts

@@ -1,2 +1,2 @@
-export declare const entrypoints: any[];
+export declare const entrypoints: import("@owlmeans/entrypoint").CommonEntrypoint[];
 //# sourceMappingURL=entrypoints.d.ts.map

package/build/entrypoints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entrypoints.d.ts","sourceRoot":"","sources":["../src/entrypoints.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,WAAW,OAAS,CAAA"}
+{"version":3,"file":"entrypoints.d.ts","sourceRoot":"","sources":["../src/entrypoints.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,WAAW,mDAAS,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/api-config-client",
-  "version": "0.1.18-rc.12",
+  "version": "0.1.18-rc.13",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,10 +21,10 @@
     }
   },
   "dependencies": {
-    "@owlmeans/api-config": "^0.1.18-rc.11",
-    "@owlmeans/client-context": "^0.1.18-rc.12",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.12",
-    "@owlmeans/context": "^0.1.18-rc.7"
+    "@owlmeans/api-config": "^0.1.18-rc.12",
+    "@owlmeans/client-context": "^0.1.18-rc.13",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.13",
+    "@owlmeans/context": "^0.1.18-rc.8"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",