refactor: services ready before setup; assets fully declarative

Invert the wire-services lifecycle so services are constructed and ready
BEFORE any setup() runs, and setup consumes them synchronously.

- adapters (initiate/build/mcp/embedded) install-loop -> ready() -> setup
- hub: two passes — dock+collect across all devframes (+ new
  initHub({ services }) host-level channel) -> ready() once -> setups ->
  configure -> ui.setup; installDevframe/prepareDevframe split accordingly
- ready() is internal; install() stays as the dynamic escape hatch
  (immediate post-ready construct)
- descriptor options deep-merge by default (objects recurse, arrays
  union-dedupe, scalars last-wins); both shipped services drop their
  custom mergeOptions (hook kept as override)
- drop the first-connect safety net + DF0071

Consumers:
- assets declares both services (service-open with the factory-computed
  managed dir as an allowed root) — no imperative install in setup;
  drops its open-in-editor/reveal-in-folder RPCs (+ DP_ASSETS_0008) and
  the client calls service-open directly with a new dev-only absolute
  AssetInfo.fsPath (reveal passes the parent dir)
- messages harness mirrors the new ordering

Docs: guide/services.md rewritten to the pre-setup lifecycle; DF0071
page removed; error pages reworded.

Author: antfubot

docs/errors/DF0066.md

@@ -10,29 +10,27 @@ outline: deep
 
 ## Cause
 
-Wire services are deduplicated by npm package name: the first installation wins, and later installs of the same package return the existing node API. Option sets from multiple installers only merge **before** the `ctx.services.ready()` barrier fires — an install that arrives after the service was constructed can no longer influence its configuration, so any options it carried are dropped with this warning.
+Wire services are deduplicated by npm package name: the first installation wins, and later installs of the same package return the existing node API. Declared services are constructed once **before setup runs**, deep-merging every declarer's options. Calling `ctx.services.install()` for an already-constructed package — the dynamic escape hatch used after that point — can no longer influence its configuration, so any options it carries are dropped with this warning.
 
 ## Example
 
 ```ts
-await ctx.services.ready()
-
-// ✗ The service is already constructed; { themes } is ignored.
-await ctx.services.install(createShikiService({ themes }))
+// The package is already declared (and constructed pre-setup) elsewhere.
+// ✗ This late install can't merge; { themes } is ignored.
+ctx.services.install(createShikiService({ themes }))
 ```
 
 ## Fix
 
-Install the service (or declare it in `DevframeDefinition.services`) before the barrier — a host's explicit installs during setup/`configure` naturally run before the adapter fires `ready()`, so its options join the merge:
+Declare the service so its options join the pre-setup merge — on the plugin's `DevframeDefinition.services`, or host-wide via `initHub({ services })`:
 
 ```ts
-await initHub({
-  async configure(ctx) {
-    ctx.services.install(createShikiService({ themes })) // ✓ merges
-  },
+initHub({
+  services: [createShikiService({ themes })], // ✓ merges before setup
+  devframes: [/* … */],
 })
 ```
 
 ## Source
 
-- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts) — `install()`/the barrier flush warn when an already-installed package is installed again.
+- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts) — `installPackage` warns when an already-installed package is installed again.

docs/errors/DF0067.md

@@ -10,7 +10,7 @@ outline: deep
 
 ## Cause
 
-A service descriptor marked `required: true` names a package that could not be resolved and imported at the `ctx.services.ready()` barrier. Descriptors resolve against the declaring plugin's own dependencies first (then the workspace root), so this usually means the service package is missing from the declarer's `dependencies`, or isn't installed.
+A service descriptor marked `required: true` names a package that could not be resolved and imported when services are constructed before setup. Descriptors resolve against the declaring plugin's own dependencies first (then the workspace root), so this usually means the service package is missing from the declarer's `dependencies`, or isn't installed.
 
 Descriptors without `required` degrade instead: the missing service is skipped and clients observe `services.has(pkg) === false`.
 
@@ -19,7 +19,7 @@ Descriptors without `required` degrade instead: the missing service is skipped a
 ```ts
 defineDevframe({
   services: [
-    // ✗ Throws at the ready() barrier when the package isn't installed.
+    // ✗ Throws before setup when the package isn't installed.
     { package: '@devframes/service-shiki', required: true },
   ],
 })
@@ -31,4 +31,4 @@ Install the service package next to whoever declares it — a plugin declaring i
 
 ## Source
 
-- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts) — the barrier flush throws when a `required` descriptor's package fails to import.
+- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts) — the pre-setup construction throws when a `required` descriptor's package fails to import.

docs/errors/DF0068.md

@@ -10,7 +10,7 @@ outline: deep
 
 ## Cause
 
-A service descriptor marked `required: true` declares a `version` range, and the version of the service that actually resolved falls outside it. The range is checked at the `ctx.services.ready()` barrier against the resolved definition's own `version`.
+A service descriptor marked `required: true` declares a `version` range, and the version of the service that actually resolved falls outside it. The range is checked when services are constructed before setup against the resolved definition's own `version`.
 
 Without `required`, the same mismatch installs the service anyway and warns with [`DF0069`](/errors/DF0069).
 
@@ -31,4 +31,4 @@ Align the installed service package with the declared range (update whichever si
 
 ## Source
 
-- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts) — the barrier flush checks each descriptor's `version` range against the resolved definition.
+- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts) — the pre-setup construction checks each descriptor's `version` range against the resolved definition.

docs/errors/DF0069.md

@@ -31,4 +31,4 @@ Align the installed service package with the declared range to silence the warni
 
 ## Source
 
-- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts) — the barrier flush checks each descriptor's `version` range against the resolved definition.
+- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts) — the pre-setup construction checks each descriptor's `version` range against the resolved definition.

docs/errors/DF0070.md

@@ -33,4 +33,4 @@ A service package's default export must be its `create<X>Service` factory, retur
 
 ## Source
 
-- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts) — `install()` validates its input; the barrier flush validates imported factories and the definitions they return.
+- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts) — `install()` validates its input; the pre-setup construction validates imported factories and the definitions they return.

docs/errors/DF0071.md

@@ -101,29 +101,36 @@ export default function createOpenService(options?: OpenServiceOptions): Devfram
 
 Two declaration merges make it fully typed for consumers: the fully-qualified RPC ids go into `DevframeRpcServerFunctions`, and the package → scope mapping into `DevframeServicesScopeRegistry` (so a client's `services.get()` returns a scoped, typed RPC handle).
 
-### Installing
+### Declaring
 
-A host with the factory at hand installs explicitly; a plugin declares what it consumes on its definition and the adapter resolves the package **against the plugin's own dependencies**:
+Services are **declarative**. A plugin lists what it consumes on its definition; a host lists shared ones on `initHub`. The adapter resolves each package — for a plugin, **against the plugin's own dependencies** — and constructs it:
 
 ```ts
-// host side (e.g. inside initHub's configure)
-ctx.services.install(createShikiService({ themes }))
-
-// plugin side — declarative
+// plugin side — on the definition
 defineDevframe({
   services: [
     { package: '@devframes/service-open' },
     { package: '@devframes/service-shiki', version: '^1', options: { langs: ['vue'] } },
   ],
 })
+
+// host side — shared services on initHub
+initHub({
+  services: [createShikiService({ themes })],
+  devframes: [/* … */],
+})
 ```
 
 Entries are optional by default — a package that isn't installed is skipped and clients see `has() === false`. Mark an entry `required: true` to fail hard instead ([`DF0067`](https://devfra.me/errors/DF0067) on a missing package, [`DF0068`](https://devfra.me/errors/DF0068) on an unsatisfied `version` range; without it a range mismatch only warns with [`DF0069`](https://devfra.me/errors/DF0069)).
 
-Installs queue until the adapter fires the `ctx.services.ready()` barrier after every devframe's setup has run. There each service is constructed **once**, with the option sets from every declarer merged — through the definition's `mergeOptions` when it declares one, otherwise shallow-merged in declaration order, so a host installing last wins. After the barrier, installing an already-installed package returns the existing API and warns ([`DF0066`](https://devfra.me/errors/DF0066)) when its options had to be ignored.
+### Lifecycle: ready before setup
+
+Services are constructed and made ready **before any `setup(ctx)` runs**. The hub collects every declared service (across all devframes plus `initHub`), constructs each **once** — deep-merging the option sets from every declarer (objects recurse, arrays union-dedupe, scalars take the later value; a service may override with its own `mergeOptions`) — and only then runs the setups. So `setup(ctx)` can consume a service synchronously via `ctx.services.get(pkg)`, including one another devframe declared.
 
 Server-side consumers get the node API from the same registry — `ctx.services.get('@devframes/service-open')` or `whenAvailable` — with no RPC hop.
 
+Declarative covers the common case. For a service whose configuration is only known at runtime, `ctx.services.install(input)` is the dynamic escape hatch: after the pre-setup construction it builds immediately; re-installing an already-constructed package returns the existing API and warns ([`DF0066`](https://devfra.me/errors/DF0066)) if it carried options that can no longer merge.
+
 ### Feature-detecting on the client
 
 Installed services are advertised through the `devframe:services` [shared state](./shared-state); the client mirrors it on `rpc.services`:

docs/guide/services.md

@@ -88,10 +88,11 @@ export async function createBuild(d: DevframeDefinition, options: CreateBuildOpt
     mode: 'build',
     host,
   })
+  // Services ready before setup, so setup can consume them synchronously.
   for (const input of d.services ?? [])
     void ctx.services.install(input, { resolveFrom: d.packageName })
-  await d.setup(ctx)
   await ctx.services.ready()
+  await d.setup(ctx)
 
   await fs.mkdir(resolve(outDir, DEVFRAME_RPC_DUMP_DIRNAME), { recursive: true })
 

packages/devframe/src/adapters/build.ts

@@ -16,10 +16,11 @@ export interface CreateEmbeddedOptions {
  * effective default follows the hosted rule of `def.basePath ?? '/__<id>/'`.
  */
 export async function createEmbedded(d: DevframeDefinition, options: CreateEmbeddedOptions): Promise<void> {
-  // Declarative services queue before setup; the owning host fires the
-  // `ctx.services.ready()` barrier (post-barrier registration installs
-  // immediately).
+  // Services ready before setup. `ready()` is idempotent: on an
+  // already-running host it's a no-op and the fresh installs construct
+  // immediately; on a not-yet-started one it fires the initial barrier.
   for (const input of d.services ?? [])
     void options.ctx.services.install(input, { resolveFrom: d.packageName })
+  await options.ctx.services.ready()
   await d.setup(options.ctx)
 }

packages/devframe/src/adapters/embedded.ts

@@ -289,12 +289,12 @@ export function initDevframe(
         host: hostImpl,
       })
       const setupInfo: DevframeSetupInfo = { flags: options.flags ?? {} }
-      // Declarative services queue ahead of setup (their promises resolve at
-      // the ready() barrier below), resolving against the plugin's own deps.
+      // Wire services are constructed and made ready BEFORE setup, so
+      // `setup(ctx)` can consume them synchronously (`ctx.services.get`).
       for (const input of def.services ?? [])
         void context.services.install(input, { resolveFrom: def.packageName })
-      await def.setup(context, setupInfo)
       await context.services.ready()
+      await def.setup(context, setupInfo)
 
       // Route-based MCP server (opt-in). Mounted before the SPA static
       // catch-all so the exact `<base>__mcp` route wins, and advertised in