@svadmin/core 0.54.0 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "author": "zuohuadong",
   "repository": {
     "type": "git",

package/src/admin-config-runtime.svelte.ts

@@ -0,0 +1,14 @@
+/**
+ * Runtime binding for `defineAdminConfig`.
+ *
+ * `provideAdminConfig` resolves the application config once during component
+ * initialization and installs the resulting ProviderBundle + ResourceDefinition
+ * list into the scoped `AdminContext` tree. It is intentionally thin: all
+ * composition and diagnostics live in the pure `admin-config` module.
+ */
+import { resolveAdminConfig, toAdminContextSource, type AdminConfig } from './admin-config';
+import { provideAdminContext, type AdminContextValue } from './context.svelte';
+
+export function provideAdminConfig(config: AdminConfig): AdminContextValue {
+  return provideAdminContext(toAdminContextSource(resolveAdminConfig(config)));
+}

package/src/admin-config.ts

@@ -0,0 +1,333 @@
+/**
+ * Application composition layer.
+ *
+ * `defineAdminConfig` is the single, AI-readable application entrypoint: it
+ * composes provider bundles, resource contracts, and plugins into one typed
+ * object without taking over business routing. `resolveAdminConfig` folds
+ * plugin contributions into a deterministic snapshot plus diagnostics, which
+ * the CLI (`doctor` / `generate`) and DevTools can inspect.
+ */
+import type { DataProvider, ResourceDefinition } from './types';
+import type { DataProviderInput, ProviderBundle } from './provider-bundle';
+import type { ResourceContract } from './resource-contract';
+
+/** Machine-readable capability vocabulary shared by plugins, generators, and `doctor`. */
+export type AdminPluginCapability =
+  | 'data'
+  | 'auth'
+  | 'access-control'
+  | 'live'
+  | 'storage'
+  | 'audit-log'
+  | 'admin-route'
+  | 'notification'
+  | 'task'
+  | 'i18n'
+  | 'ai'
+  | 'dashboard'
+  | 'import-export'
+  | 'feature-flag';
+
+export interface AdminPluginDocs {
+  readonly setup?: string;
+  readonly examples?: string;
+}
+
+/** Runtime contributions a plugin may add to the application. */
+export interface AdminPluginContribution {
+  readonly resources?: readonly AdminResourceInput[];
+  readonly providers?: ProviderBundle;
+}
+
+/**
+ * Declarative plugin manifest. The descriptor is data, not behavior: it lets
+ * `add`, `generate`, `doctor`, docs, and AI tooling discover what a plugin can
+ * do without importing its runtime implementation.
+ */
+export interface AdminPluginDescriptor {
+  readonly name: string;
+  readonly version: string;
+  readonly capabilities: readonly AdminPluginCapability[];
+  /** Optional JSON-schema-like config contract (for example a TypeBox schema). */
+  readonly configSchema?: unknown;
+  readonly providers?: readonly string[];
+  readonly commands?: readonly string[];
+  readonly generators?: readonly string[];
+  readonly docs?: AdminPluginDocs;
+  readonly contributes?: AdminPluginContribution;
+}
+
+export function defineSvadminPlugin<const TPlugin extends AdminPluginDescriptor>(
+  plugin: TPlugin,
+): TPlugin {
+  if (!plugin.name.trim()) {
+    throw new Error('defineSvadminPlugin requires a non-empty name');
+  }
+  if (!plugin.version.trim()) {
+    throw new Error(`Plugin "${plugin.name}" requires a non-empty version`);
+  }
+  const duplicates = duplicateValues(plugin.capabilities);
+  if (duplicates.length > 0) {
+    throw new Error(`Plugin "${plugin.name}" declares duplicate capabilities: ${duplicates.join(', ')}`);
+  }
+  return plugin;
+}
+
+export interface AdminConfigInput {
+  readonly name?: string;
+  /** Either a first-class ProviderBundle or several bundles composed in order. */
+  readonly providers: ProviderBundle | readonly ProviderBundle[];
+  /**
+   * Schema-first resources. A bare `ResourceContract` is expanded into a minimal
+   * `ResourceDefinition`; a full definition may embed `contract` for menu/label metadata.
+   */
+  readonly resources?: readonly AdminResourceInput[];
+  readonly plugins?: readonly AdminPluginDescriptor[];
+}
+
+/** A full resource definition is required to carry its runtime contract. */
+export interface AdminResourceDefinition extends ResourceDefinition {
+  readonly contract: ResourceContract;
+}
+
+/**
+ * Schema-first resources are preferred, but plain definitions remain accepted so
+ * existing projects migrate without rewrites. Bare contracts are expanded.
+ */
+export type AdminResourceInput = ResourceContract | ResourceDefinition;
+
+export interface AdminConfig extends AdminConfigInput {
+  readonly __svadminConfig: true;
+}
+
+/**
+ * Typed, identity-preserving application configuration. Returns the input
+ * object with the config brand so downstream resolution can assert the shape.
+ */
+export function defineAdminConfig<const TConfig extends AdminConfigInput>(
+  config: TConfig,
+): TConfig & { readonly __svadminConfig: true } {
+  if (isProviderBundleList(config.providers) && config.providers.length === 0) {
+    throw new Error('defineAdminConfig requires at least one provider bundle');
+  }
+  return { ...config, __svadminConfig: true };
+}
+
+export type AdminConfigDiagnosticCode =
+  | 'duplicate-resource'
+  | 'duplicate-plugin'
+  | 'invalid-resource'
+  | 'invalid-plugin-contribution';
+
+export interface AdminConfigDiagnostic {
+  readonly code: AdminConfigDiagnosticCode;
+  readonly message: string;
+  readonly source?: string;
+}
+
+export interface ResolvedAdminConfig {
+  readonly name: string | undefined;
+  /** Composed bundle; later bundles override earlier scalar providers. */
+  readonly providers: ProviderBundle;
+  /** Normalized definitions ready to pass to `provideAdminContext`. */
+  readonly resources: readonly ResourceDefinition[];
+  readonly plugins: readonly AdminPluginDescriptor[];
+  readonly diagnostics: readonly AdminConfigDiagnostic[];
+}
+
+/** The `provideAdminContext` source derived from a resolved config. */
+export interface ResolvedAdminContextSource {
+  readonly providerBundle: ProviderBundle;
+  readonly resources: ResourceDefinition[];
+}
+
+function isSingleDataProvider(value: DataProviderInput): value is DataProvider {
+  return typeof Reflect.get(value, 'getList') === 'function';
+}
+
+function duplicateValues<T>(values: readonly T[]): T[] {
+  const seen = new Set<T>();
+  const duplicates = new Set<T>();
+  for (const value of values) {
+    if (seen.has(value)) duplicates.add(value);
+    else seen.add(value);
+  }
+  return [...duplicates];
+}
+
+function isProviderBundleList(
+  value: ProviderBundle | readonly ProviderBundle[],
+): value is readonly ProviderBundle[] {
+  return Array.isArray(value);
+}
+
+function providerBundlesOf(config: AdminConfigInput): readonly ProviderBundle[] {
+  return isProviderBundleList(config.providers) ? config.providers : [config.providers];
+}
+
+function mergeDataProvider(inputs: readonly DataProviderInput[]): DataProviderInput {
+  const named: Record<string, DataProvider> = {};
+  let fallback: DataProvider | undefined;
+  for (const input of inputs) {
+    if (isSingleDataProvider(input)) fallback = input;
+    else Object.assign(named, input);
+  }
+  if (Object.keys(named).length === 0) {
+    if (fallback === undefined) throw new Error('resolveAdminConfig requires a data provider');
+    return fallback;
+  }
+  if (fallback !== undefined && named['default'] === undefined) {
+    return { ...named, default: fallback };
+  }
+  return named;
+}
+
+function mergeProviderBundles(
+  bundles: readonly ProviderBundle[],
+): ProviderBundle {
+  const dataProviderInputs: DataProviderInput[] = [];
+  let merged: ProviderBundle | undefined;
+  for (const bundle of bundles) {
+    dataProviderInputs.push(bundle.dataProvider);
+    merged = merged === undefined ? { ...bundle } : mergeOptionalProviders(merged, bundle);
+  }
+  if (merged === undefined) throw new Error('resolveAdminConfig requires a data provider');
+  const dataProvider = mergeDataProvider(dataProviderInputs);
+  return { ...merged, dataProvider };
+}
+
+function mergeOptionalProviders(base: ProviderBundle, override: ProviderBundle): ProviderBundle {
+  return {
+    dataProvider: override.dataProvider,
+    ...(override.authProvider !== undefined ? { authProvider: override.authProvider } : base.authProvider !== undefined ? { authProvider: base.authProvider } : {}),
+    ...(override.accessControlProvider !== undefined ? { accessControlProvider: override.accessControlProvider } : base.accessControlProvider !== undefined ? { accessControlProvider: base.accessControlProvider } : {}),
+    ...(override.liveProvider !== undefined ? { liveProvider: override.liveProvider } : base.liveProvider !== undefined ? { liveProvider: base.liveProvider } : {}),
+    ...(override.auditLogProvider !== undefined ? { auditLogProvider: override.auditLogProvider } : base.auditLogProvider !== undefined ? { auditLogProvider: base.auditLogProvider } : {}),
+    ...(override.notificationProvider !== undefined ? { notificationProvider: override.notificationProvider } : base.notificationProvider !== undefined ? { notificationProvider: base.notificationProvider } : {}),
+    ...(override.chatProvider !== undefined ? { chatProvider: override.chatProvider } : base.chatProvider !== undefined ? { chatProvider: base.chatProvider } : {}),
+    ...(override.agentProvider !== undefined ? { agentProvider: override.agentProvider } : base.agentProvider !== undefined ? { agentProvider: base.agentProvider } : {}),
+    ...(override.taskProvider !== undefined ? { taskProvider: override.taskProvider } : base.taskProvider !== undefined ? { taskProvider: base.taskProvider } : {}),
+    ...(override.routerProvider !== undefined ? { routerProvider: override.routerProvider } : base.routerProvider !== undefined ? { routerProvider: base.routerProvider } : {}),
+    ...(override.tenantAdapter !== undefined ? { tenantAdapter: override.tenantAdapter } : base.tenantAdapter !== undefined ? { tenantAdapter: base.tenantAdapter } : {}),
+    ...(override.organizationProvider !== undefined ? { organizationProvider: override.organizationProvider } : base.organizationProvider !== undefined ? { organizationProvider: base.organizationProvider } : {}),
+    ...(override.identityGovernanceProvider !== undefined ? { identityGovernanceProvider: override.identityGovernanceProvider } : base.identityGovernanceProvider !== undefined ? { identityGovernanceProvider: base.identityGovernanceProvider } : {}),
+    ...(override.sessionProvider !== undefined ? { sessionProvider: override.sessionProvider } : base.sessionProvider !== undefined ? { sessionProvider: base.sessionProvider } : {}),
+    ...(override.credentialProvider !== undefined ? { credentialProvider: override.credentialProvider } : base.credentialProvider !== undefined ? { credentialProvider: base.credentialProvider } : {}),
+  };
+}
+
+function isResourceContract(value: AdminResourceInput): value is ResourceContract {
+  return !Array.isArray(Reflect.get(value, 'fields'));
+}
+
+/** Expands bare contracts into minimal definitions; keeps full definitions intact. */
+export function normalizeAdminResource(value: AdminResourceInput): ResourceDefinition {
+  if (!isResourceContract(value)) return value;
+  return { name: value.name, label: value.name, fields: [], contract: value };
+}
+
+function collectPluginResources(
+  plugins: readonly AdminPluginDescriptor[],
+  diagnostics: AdminConfigDiagnostic[],
+): AdminResourceInput[] {
+  const resources: AdminResourceInput[] = [];
+  for (const plugin of plugins) {
+    for (const resource of plugin.contributes?.resources ?? []) {
+      if (!resource.name.trim()) {
+        diagnostics.push({
+          code: 'invalid-plugin-contribution',
+          message: `Plugin "${plugin.name}" contributes a resource without a name`,
+          source: plugin.name,
+        });
+        continue;
+      }
+      resources.push(resource);
+    }
+  }
+  return resources;
+}
+
+function collectPluginProviders(
+  plugins: readonly AdminPluginDescriptor[],
+  diagnostics: AdminConfigDiagnostic[],
+): ProviderBundle[] {
+  const bundles: ProviderBundle[] = [];
+  for (const plugin of plugins) {
+    const providers = plugin.contributes?.providers;
+    if (providers === undefined) continue;
+    if (isSingleDataProvider(providers.dataProvider) === false && Object.keys(providers.dataProvider).length === 0) {
+      diagnostics.push({
+        code: 'invalid-plugin-contribution',
+        message: `Plugin "${plugin.name}" contributes an empty provider bundle`,
+        source: plugin.name,
+      });
+      continue;
+    }
+    bundles.push(providers);
+  }
+  return bundles;
+}
+
+/**
+ * Folds plugin contributions into a deterministic application snapshot.
+ * Never throws on recoverable conflicts; inspect `diagnostics` instead.
+ */
+export function resolveAdminConfig(config: AdminConfig): ResolvedAdminConfig {
+  const diagnostics: AdminConfigDiagnostic[] = [];
+  const plugins = config.plugins ?? [];
+
+  const pluginNames = plugins.map((plugin) => plugin.name);
+  for (const duplicate of duplicateValues(pluginNames)) {
+    diagnostics.push({
+      code: 'duplicate-plugin',
+      message: `Plugin "${duplicate}" is registered more than once`,
+      source: duplicate,
+    });
+  }
+
+  const pluginResources = collectPluginResources(plugins, diagnostics);
+  const resources = [...(config.resources ?? []), ...pluginResources].map(normalizeAdminResource);
+  const resourceNames = new Set<string>();
+  for (const resource of resources) {
+    if (!resource.name.trim()) {
+      diagnostics.push({ code: 'invalid-resource', message: 'A resource is defined without a name' });
+      continue;
+    }
+    if (resourceNames.has(resource.name)) {
+      diagnostics.push({
+        code: 'duplicate-resource',
+        message: `Resource "${resource.name}" is registered more than once`,
+        source: resource.name,
+      });
+    }
+    resourceNames.add(resource.name);
+  }
+
+  const providers = mergeProviderBundles(
+    [...providerBundlesOf(config), ...collectPluginProviders(plugins, diagnostics)],
+  );
+
+  return {
+    name: config.name,
+    providers,
+    resources,
+    plugins,
+    diagnostics,
+  };
+}
+
+/** Builds the `provideAdminContext` source from a resolved config. */
+export function toAdminContextSource(config: ResolvedAdminConfig): ResolvedAdminContextSource {
+  return { providerBundle: config.providers, resources: [...config.resources] };
+}
+
+/** Throws when resolution produced error diagnostics; useful at app startup and in `doctor`. */
+export function assertAdminConfig(config: AdminConfig): ResolvedAdminConfig {
+  const resolved = resolveAdminConfig(config);
+  if (resolved.diagnostics.length > 0) {
+    throw new Error(
+      `Invalid admin config:\n${resolved.diagnostics.map((entry) => `- [${entry.code}] ${entry.message}`).join('\n')}`,
+    );
+  }
+  return resolved;
+}

package/src/admin-manifest.ts

@@ -0,0 +1,132 @@
+/**
+ * AI manifest builder.
+ *
+ * Serializes a resolved application config into the stable, JSON-safe entrypoint
+ * that AI tooling and `svadmin doctor` read instead of scanning the repository.
+ * The output is intentionally small and deterministic: providers, resources,
+ * plugin capabilities, project commands, and generated-file guardrails.
+ */
+import { getContractFormFields, type ResourceContract } from './resource-contract';
+import type { AdminPluginCapability, ResolvedAdminConfig } from './admin-config';
+import type { DataProvider } from './types';
+
+/** Project-level facts that are not part of the runtime config. */
+export interface AdminManifestProject {
+  readonly name?: string;
+  readonly commands?: Readonly<Record<string, string>>;
+  /** Internal import paths AI-generated code must never reach into. */
+  readonly forbiddenImports?: readonly string[];
+  readonly testCommand?: string;
+}
+
+export interface AdminManifestField {
+  readonly key: string;
+  readonly label: string;
+  readonly type: string;
+  readonly required: boolean;
+}
+
+export interface AdminManifestResource {
+  readonly name: string;
+  readonly label: string;
+  readonly fields: readonly AdminManifestField[];
+  /** Field names that must be present per operation, derived from the contract. */
+  readonly contract: {
+    readonly record: readonly string[];
+    readonly create: readonly string[];
+    readonly update: readonly string[];
+  };
+}
+
+export interface AdminManifestPlugin {
+  readonly name: string;
+  readonly version: string;
+  readonly capabilities: readonly AdminPluginCapability[];
+  readonly configSchema?: unknown;
+}
+
+export interface AdminManifest {
+  readonly version: 1;
+  readonly project: {
+    readonly name: string | undefined;
+    readonly commands: Readonly<Record<string, string>>;
+    readonly testCommand: string | undefined;
+    readonly forbiddenImports: readonly string[];
+  };
+  readonly providers: {
+    readonly dataProviders: readonly string[];
+    readonly scalarProviders: readonly string[];
+  };
+  readonly resources: readonly AdminManifestResource[];
+  readonly plugins: readonly AdminManifestPlugin[];
+}
+
+function isSingleDataProvider(value: unknown): value is DataProvider {
+  return typeof Reflect.get(value as object, 'getList') === 'function';
+}
+
+function dataProviderNames(config: ResolvedAdminConfig): string[] {
+  const dataProvider = config.providers.dataProvider;
+  if (isSingleDataProvider(dataProvider)) return ['default'];
+  return Object.keys(dataProvider);
+}
+
+function scalarProviderNames(config: ResolvedAdminConfig): string[] {
+  const names: string[] = [];
+  for (const key of Object.keys(config.providers)) {
+    if (key === 'dataProvider') continue;
+    if (Reflect.get(config.providers, key) !== undefined) names.push(key);
+  }
+  return names.sort();
+}
+
+function contractFields(contract: ResourceContract, action: 'show' | 'create' | 'edit'): string[] {
+  try {
+    return getContractFormFields(contract, action);
+  } catch {
+    return [];
+  }
+}
+
+/** Builds the stable AI entrypoint from a resolved config. */
+export function buildAdminManifest(
+  config: ResolvedAdminConfig,
+  project: AdminManifestProject = {},
+): AdminManifest {
+  return {
+    version: 1,
+    project: {
+      name: project.name ?? config.name,
+      commands: { ...(project.commands ?? {}) },
+      testCommand: project.testCommand,
+      forbiddenImports: [...(project.forbiddenImports ?? [])],
+    },
+    providers: {
+      dataProviders: dataProviderNames(config),
+      scalarProviders: scalarProviderNames(config),
+    },
+    resources: config.resources.map((resource) => ({
+      name: resource.name,
+      label: resource.label,
+      fields: resource.fields.map((field) => ({
+        key: field.key,
+        label: field.label,
+        type: field.type,
+        required: field.required ?? false,
+      })),
+      contract: resource.contract === undefined
+        ? { record: [], create: [], update: [] }
+        : {
+            record: contractFields(resource.contract, 'show'),
+            create: contractFields(resource.contract, 'create'),
+            update: contractFields(resource.contract, 'edit'),
+          },
+    })),
+    plugins: config.plugins.map((plugin) => ({
+      name: plugin.name,
+      version: plugin.version,
+      capabilities: plugin.capabilities,
+      ...(plugin.configSchema !== undefined ? { configSchema: plugin.configSchema } : {}),
+    })),
+  };
+}

package/src/index.ts

@@ -67,7 +67,40 @@ export {
   useCreate, useUpdate, useDelete, useCreateMany, useUpdateMany, useDeleteMany, useForm,
   useInvalidate,
 } from './strict-hooks.svelte';
-export { defineResource, getContractFormFields } from './resource-contract';
+export { defineResource, getContractFormFields, withContractProjection } from './resource-contract';
+export {
+  defineAdminConfig,
+  defineSvadminPlugin,
+  resolveAdminConfig,
+  assertAdminConfig,
+  toAdminContextSource,
+  normalizeAdminResource,
+} from './admin-config';
+export type {
+  AdminConfig,
+  AdminConfigDiagnostic,
+  AdminConfigDiagnosticCode,
+  AdminConfigInput,
+  AdminPluginCapability,
+  AdminPluginContribution,
+  AdminPluginDescriptor,
+  AdminPluginDocs,
+  AdminResourceDefinition,
+  AdminResourceInput,
+  ResolvedAdminConfig,
+  ResolvedAdminContextSource,
+} from './admin-config';
+export { provideAdminConfig } from './admin-config-runtime.svelte';
+export { provideResourceScope } from './resource-scope.svelte';
+export type { ResourceScope } from './resource-scope.svelte';
+export { buildAdminManifest } from './admin-manifest';
+export type {
+  AdminManifest,
+  AdminManifestField,
+  AdminManifestPlugin,
+  AdminManifestProject,
+  AdminManifestResource,
+} from './admin-manifest';
 export { UpdateManyPartialError } from './update-many-contract';
 export { CreateManyPartialError } from './create-many-contract';
 export type { ContractCreateOptions as UseCreateOptions } from './create-hooks.svelte';
@@ -77,6 +110,7 @@ export type { ContractUpdateParams as UseUpdateMutateParams } from './update-con
 export type { ContractDeleteOptions as UseDeleteOptions } from './delete-hooks.svelte';
 export type { ContractDeleteParams as UseDeleteMutateParams } from './delete-contract';
 export type { ContractFormAction, ContractFormDraft, ContractFormValues } from './resource-contract';
+export type { ContractProjectionOptions } from './resource-contract';
 export type { ResourceContract, ContractSchemas, ContractRecord, ContractId, ContractInput } from './resource-contract';
 export type { ContractFilter, ContractSort } from './strict-hooks.svelte';
 export { defineCommand } from './command-contract';

package/src/resource-contract.ts

@@ -2,8 +2,8 @@ import { CloneType, Kind, TransformKind, Type, type Static, type TObject, type T
 import { checkExact, createExactSchemaValidator } from './schema-validation';
 import { TypeGuard } from '@sinclair/typebox/type';
 import { DeleteManyPartialError, HttpError, type DataProvider, type KnownResources, type BaseRecord,
-  type GetManyParams, type CreateManyParams, type UpdateManyParams, type DeleteManyParams,
-  type GetOneResult, type GetManyResult } from './types';
+  type GetListResult, type GetManyParams, type CreateManyParams, type UpdateManyParams, type DeleteManyParams,
+  type GetOneParams, type GetOneResult, type GetManyResult } from './types';
 import { withResourceSchemas, createResourceRequestValidator, type ResourceSchemas } from './resource-schemas';
 import { decodeBaseRecord } from './record-decoder';
 import { snapshotPlainData } from './plain-data';
@@ -166,6 +166,115 @@ export function parseContractRecord(contract: ResourceContract, value: unknown):
   throw new HttpError('Invalid provider response', 502, undefined, { code: 'INVALID_PROVIDER_RESPONSE' });
 }
 
+export interface ContractProjectionOptions {
+  /** Supplies the id when the backend record has no declared contract id. */
+  readonly getId?: (input: {
+    resource: string;
+    requestedId: string | number | undefined;
+    record: unknown;
+    index: number;
+  }) => string | number | undefined;
+}
+
+function projectBySchema(schema: TSchema, value: unknown): unknown {
+  if (TypeGuard.IsObject(schema)) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return value;
+    const source = value as Record<string, unknown>;
+    const projected: Record<string, unknown> = {};
+    for (const [key, property] of Object.entries(schema.properties)) {
+      if (Object.hasOwn(source, key)) projected[key] = projectBySchema(property, source[key]);
+    }
+    return projected;
+  }
+  if (TypeGuard.IsArray(schema)) {
+    return Array.isArray(value) ? value.map(item => projectBySchema(schema.items, item)) : value;
+  }
+  if (TypeGuard.IsTuple(schema)) {
+    return Array.isArray(value)
+      ? value.map((item, index) => schema.items?.[index] ? projectBySchema(schema.items[index], item) : item)
+      : value;
+  }
+  if (TypeGuard.IsUnion(schema)) {
+    const branch = schema.anyOf.find(candidate => checkExact(candidate, value));
+    return branch ? projectBySchema(branch, value) : value;
+  }
+  return value;
+}
+
+function projectRecord(
+  contract: ResourceContract,
+  resource: string,
+  record: unknown,
+  index: number,
+  requestedId: string | number | undefined,
+  options: ContractProjectionOptions,
+): unknown {
+  const projected = projectBySchema(definitionOf(contract).schemas.record, record);
+  if (typeof projected !== 'object' || projected === null || Array.isArray(projected)) return projected;
+  const result = projected as Record<string, unknown>;
+  if (!Object.hasOwn(result, 'id')) {
+    const id = options.getId?.({ resource, requestedId, record, index })
+      ?? requestedId
+      ?? (typeof record === 'object' && record !== null && !Array.isArray(record)
+        ? ['id', '_id', 'uuid', 'key', 'name'].map(key => (record as Record<string, unknown>)[key])
+          .find(candidate => typeof candidate === 'string' || typeof candidate === 'number')
+        : undefined)
+      ?? `${resource}:${index}`;
+    result['id'] = id;
+  }
+  return result;
+}
+
+/**
+ * Projects read responses into the exact closed shape required by resource contracts.
+ * Write responses remain untouched so mutation validation keeps its existing semantics.
+ */
+export function withContractProjection(
+  provider: DataProvider,
+  contracts: Readonly<Record<string, ResourceContract>>,
+  options: ContractProjectionOptions = {},
+): Readonly<DataProvider> {
+  function contractFor(resource: string): ResourceContract | undefined {
+    return contracts[resource];
+  }
+  function projectList(resource: string, result: GetListResult): GetListResult {
+    const contract = contractFor(resource);
+    if (!contract) return result;
+    return {
+      ...result,
+      data: result.data.map((record, index) =>
+        projectRecord(contract, resource, record, index, undefined, options) as BaseRecord),
+    };
+  }
+  function projectMany(resource: string, result: GetManyResult): GetManyResult {
+    const contract = contractFor(resource);
+    if (!contract) return result;
+    return {
+      ...result,
+      data: result.data.map((record, index) =>
+        projectRecord(contract, resource, record, index, undefined, options) as BaseRecord),
+    };
+  }
+  function projectOne(params: GetOneParams, result: GetOneResult): GetOneResult {
+    const contract = contractFor(params.resource);
+    return contract
+      ? { ...result, data: projectRecord(contract, params.resource, result.data, 0, params.id, options) as BaseRecord }
+      : result;
+  }
+
+  const adapted: DataProvider = {
+    ...provider,
+    getList: async params => projectList(params.resource, await provider.getList(params)),
+    getOne: async params => projectOne(params, await provider.getOne(params)),
+    getApiUrl: () => provider.getApiUrl(),
+  };
+  if (provider.getMany) {
+    const getMany = provider.getMany.bind(provider);
+    adapted.getMany = async params => projectMany(params.resource, await getMany(params));
+  }
+  return Object.freeze(adapted);
+}
+
 function idSchema(schemas: ContractSchemas): TSchema {
   const schema = schemas.record.properties['id'];
   if (!schema) throw new HttpError('Missing contract ID schema', 400, undefined, { code: 'INVALID_RESOURCE_CONTRACT' });

package/src/resource-scope.svelte.ts

@@ -0,0 +1,39 @@
+/**
+ * Scoped provider/resource overrides.
+ *
+ * `provideAdminConfig` (or `AdminApp`) establishes the application scope. Calling
+ * `provideResourceScope` in any descendant subtree adds a narrower scope without
+ * touching global state, giving the four practical levels:
+ *
+ *   Application (provideAdminConfig)
+ *     -> Route (provideResourceScope in the route component)
+ *       -> Resource (provideResourceScope with one resource)
+ *         -> Component (provideResourceScope in a widget)
+ *
+ * Providers and the resource list inherit from the nearest parent unless
+ * explicitly overridden.
+ */
+import { getAdminContext, provideAdminContext, type AdminContextValue } from './context.svelte';
+import type { ProviderBundle } from './provider-bundle';
+import type { ResourceDefinition } from './types';
+
+export interface ResourceScope {
+  /** Restrict the visible resource registry for this subtree. */
+  readonly resources?: readonly ResourceDefinition[];
+  /** Swap the provider bundle for this subtree (for example a different backend). */
+  readonly providerBundle?: ProviderBundle;
+}
+
+export function provideResourceScope(scope: ResourceScope): AdminContextValue {
+  const parent = getAdminContext();
+  if (parent === undefined) {
+    throw new Error(
+      'provideResourceScope requires an existing AdminContext; call provideAdminConfig or render AdminApp first',
+    );
+  }
+  return provideAdminContext({
+    providerBundle: scope.providerBundle ?? parent.providerBundle,
+    resources: scope.resources !== undefined ? [...scope.resources] : parent.resources,
+    ...(parent.tenant === undefined ? {} : { tenant: parent.tenant }),
+  });
+}