schema-components 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## [1.4.0](https://github.com/Mearman/schema-components/compare/v1.3.3...v1.4.0) (2026-05-14)
+
+### Features
+
+* add scoped widget resolution at instance, context, and global levels ([b330baf](https://github.com/Mearman/schema-components/commit/b330baf183d00bebf999108f16c9dabd40c243be))
+
+### Documentation
+
+* update README with scoped widget resolution documentation ([21ac50d](https://github.com/Mearman/schema-components/commit/21ac50dc9a55144fc319fcf482ffad6a16585a27))
+
+## [1.3.3](https://github.com/Mearman/schema-components/compare/v1.3.2...v1.3.3) (2026-05-14)
+
+### Refactoring
+
+* extract pure resolution layer from openapi components ([5e0ab32](https://github.com/Mearman/schema-components/commit/5e0ab32de44b41b23e74082886a5ae881b418883))
+
+### Tests
+
+* add guards unit tests ([39f53ab](https://github.com/Mearman/schema-components/commit/39f53abf4cf30f1751a09267f34990c4a2532567))
+* add openapi resolution and component unit tests ([75a5892](https://github.com/Mearman/schema-components/commit/75a589220f05b5649a531bec946a63093e824687))
+* add renderer utility unit tests ([3ca3677](https://github.com/Mearman/schema-components/commit/3ca367709acf6324a33a79adf3799528971defc2))
+* expand html and streaming coverage, tighten vitest config ([ac480cd](https://github.com/Mearman/schema-components/commit/ac480cdeb39cf2ae0fa3107de2abae39102cfa26))
+
 ## [1.3.2](https://github.com/Mearman/schema-components/compare/v1.3.1...v1.3.2) (2026-05-14)
 
 ### Refactoring

package/README.md

@@ -434,7 +434,15 @@ Custom resolvers fall back to the default for any type you don't override.
 
 ## Custom widgets
 
-Register widgets by `.meta({ component })` hint:
+Widgets let you override rendering for specific fields using `.meta({ component: name })`. Three scopes are available, checked in order:
+
+1. **Instance** — `widgets` prop on `<SchemaComponent>`
+2. **Context** — `widgets` prop on `<SchemaProvider>`
+3. **Global** — `registerWidget()` for app-wide defaults
+
+If none match, the theme adapter or headless default handles the field.
+
+### Global registration
 
 ```tsx
 import { registerWidget } from "schema-components/react/SchemaComponent";
@@ -443,13 +451,65 @@ registerWidget("richtext", ({ value, onChange }) => (
   <RichTextEditor value={value} onChange={onChange} />
 ));
 
-// In schema
 const schema = z.object({
   bio: z.string().meta({ component: "richtext" }),
 });
 ```
 
-Resolution order: `.meta({ component })` → registered widget → theme adapter → headless default.
+### Context-scoped widgets
+
+Share widgets across a subtree via `<SchemaProvider>`:
+
+```tsx
+import { SchemaProvider } from "schema-components/react/SchemaComponent";
+import type { WidgetMap } from "schema-components/react/SchemaComponent";
+
+const adminWidgets: WidgetMap = new Map([
+  ["richtext", ({ value, onChange }) => <RichTextEditor value={value} onChange={onChange} />],
+  ["avatar", ({ value, onChange }) => <AvatarUploader value={value} onChange={onChange} />],
+]);
+
+<SchemaProvider resolver={shadcnResolver} widgets={adminWidgets}>
+  <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
+  <SchemaComponent schema={profileSchema} value={profile} onChange={setProfile} />
+</SchemaProvider>
+```
+
+### Instance-scoped widgets
+
+Override widgets for a single form:
+
+```tsx
+const formWidgets: WidgetMap = new Map([
+  ["richtext", ({ value, onChange }) => <SimpleTextarea value={value} onChange={onChange} />],
+]);
+
+<SchemaComponent schema={formSchema} value={form} widgets={formWidgets} />
+```
+
+### Resolution order
+
+```.meta({ component }) hint → instance widgets → context widgets → global registerWidget() → theme adapter → headless default
+```
+
+Instance overrides context. Context overrides global. Unhinted fields skip the widget layer entirely.
+
+### `WidgetMap` type
+
+```tsx
+import type { WidgetMap } from "schema-components/react/SchemaComponent";
+
+// ReadonlyMap<string, (props: RenderProps) => unknown>
+const widgets: WidgetMap = new Map([
+  ["name", (props) => <MyInput {...props} />],
+]);
+```
+
+Server Components: `<SchemaView>` accepts a `widgets` prop directly (no React context available):
+
+```tsx
+<SchemaView schema={schema} value={data} widgets={serverWidgets} />
+```
 
 ## Validation
 

package/dist/openapi/components.d.mts

@@ -1,4 +1,5 @@
 import { c as InferResponseFields, m as SchemaMeta, o as InferParameterOverrides, r as FieldOverride, s as InferRequestBodyFields } from "../types-DDCD6Xnx.mjs";
+import { WidgetMap } from "../react/SchemaComponent.mjs";
 import { ReactNode } from "react";
 
 //#region src/openapi/components.d.ts
@@ -11,6 +12,8 @@ interface ApiOperationProps<Doc = unknown, Path extends string = string, Method
   responseValue?: unknown;
   meta?: SchemaMeta;
   requestBodyFields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path, Method> : Record<string, FieldOverride>;
+  /** Instance-scoped widgets. */
+  widgets?: WidgetMap;
 }
 declare function ApiOperation<Doc = unknown, Path extends string = string, Method extends string = string>({
   schema: doc,
@@ -20,7 +23,8 @@ declare function ApiOperation<Doc = unknown, Path extends string = string, Metho
   onRequestBodyChange,
   responseValue,
   meta,
-  requestBodyFields
+  requestBodyFields,
+  widgets
 }: ApiOperationProps<Doc, Path, Method>): ReactNode;
 interface ApiParametersProps<Doc = unknown, Path extends string = string, Method extends string = string> {
   schema: Doc;
@@ -28,13 +32,16 @@ interface ApiParametersProps<Doc = unknown, Path extends string = string, Method
   method: Method;
   meta?: SchemaMeta;
   overrides?: Doc extends Record<string, unknown> ? InferParameterOverrides<Doc, Path, Method> : Record<string, FieldOverride>;
+  /** Instance-scoped widgets. */
+  widgets?: WidgetMap;
 }
 declare function ApiParameters<Doc = unknown, Path extends string = string, Method extends string = string>({
   schema: doc,
   path,
   method,
   meta,
-  overrides
+  overrides,
+  widgets
 }: ApiParametersProps<Doc, Path, Method>): ReactNode;
 interface ApiRequestBodyProps<Doc = unknown, Path extends string = string, Method extends string = string> {
   schema: Doc;
@@ -44,6 +51,8 @@ interface ApiRequestBodyProps<Doc = unknown, Path extends string = string, Metho
   onChange?: (value: unknown) => void;
   meta?: SchemaMeta;
   fields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path, Method> : Record<string, FieldOverride>;
+  /** Instance-scoped widgets. */
+  widgets?: WidgetMap;
 }
 declare function ApiRequestBody<Doc = unknown, Path extends string = string, Method extends string = string>({
   schema: doc,
@@ -52,7 +61,8 @@ declare function ApiRequestBody<Doc = unknown, Path extends string = string, Met
   value,
   onChange,
   meta,
-  fields
+  fields,
+  widgets
 }: ApiRequestBodyProps<Doc, Path, Method>): ReactNode;
 interface ApiResponseProps<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string> {
   schema: Doc;
@@ -62,6 +72,8 @@ interface ApiResponseProps<Doc = unknown, Path extends string = string, Method e
   value?: unknown;
   meta?: SchemaMeta;
   fields?: Doc extends Record<string, unknown> ? InferResponseFields<Doc, Path, Method, Status> : Record<string, FieldOverride>;
+  /** Instance-scoped widgets. */
+  widgets?: WidgetMap;
 }
 declare function ApiResponse<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string>({
   schema: doc,
@@ -70,7 +82,8 @@ declare function ApiResponse<Doc = unknown, Path extends string = string, Method
   status,
   value,
   meta,
-  fields
+  fields,
+  widgets
 }: ApiResponseProps<Doc, Path, Method, Status>): ReactNode;
 //#endregion
 export { ApiOperation, ApiOperationProps, ApiParameters, ApiParametersProps, ApiRequestBody, ApiRequestBodyProps, ApiResponse, ApiResponseProps };

package/dist/openapi/components.mjs

@@ -1,23 +1,12 @@
-import { isObject, toRecordOrUndefined } from "../core/guards.mjs";
+import { toRecordOrUndefined } from "../core/guards.mjs";
 import { normaliseSchema } from "../core/adapter.mjs";
 import { SchemaNormalisationError } from "../core/errors.mjs";
 import { walk } from "../core/walker.mjs";
-import { getParameters, getRequestBody, getResponses, listOperations, parseOpenApiDocument } from "./parser.mjs";
 import { renderField } from "../react/SchemaComponent.mjs";
+import { resolveOperation, resolveParameters, resolveRequestBody, resolveResponse, toDoc } from "./resolve.mjs";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/openapi/components.tsx
-const docCache = /* @__PURE__ */ new WeakMap();
-function getParsed(doc) {
-	const cached = docCache.get(doc);
-	if (cached !== void 0) return cached;
-	const parsed = parseOpenApiDocument(doc);
-	docCache.set(doc, parsed);
-	return parsed;
-}
 function noop() {}
-function toDoc(value) {
-	return isObject(value) ? value : {};
-}
 function renderSchema(schema, rootDocument, options) {
 	let jsonSchema;
 	let rootMeta;
@@ -38,65 +27,62 @@ function renderSchema(schema, rootDocument, options) {
 		rootDocument
 	};
 	const tree = walk(jsonSchema, walkOpts);
-	const renderChild = (childTree, childValue, childOnChange) => renderField(childTree, childValue, childOnChange, void 0, renderChild);
-	return renderField(tree, options.value, options.onChange ?? noop, void 0, renderChild);
+	const renderChild = (childTree, childValue, childOnChange) => renderField(childTree, childValue, childOnChange, void 0, renderChild, options.widgets);
+	return renderField(tree, options.value, options.onChange ?? noop, void 0, renderChild, options.widgets);
 }
-function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields }) {
-	const parsed = getParsed(toDoc(doc));
+function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields, widgets }) {
 	const rootDoc = toDoc(doc);
-	const operation = listOperations(parsed).find((op) => op.path === path && op.method === method);
-	if (operation === void 0) throw new SchemaNormalisationError(`Operation not found: ${method.toUpperCase()} ${path}`, doc, "openapi-invalid");
-	const params = getParameters(parsed, path, method);
-	const requestBody = getRequestBody(parsed, path, method);
-	const responses = getResponses(parsed, path, method);
+	const resolved = resolveOperation(rootDoc, path, method);
 	return /* @__PURE__ */ jsxs("section", {
 		"data-operation": `${method.toUpperCase()} ${path}`,
 		children: [
-			/* @__PURE__ */ jsx(OperationHeader, { operation }),
-			params.length > 0 && /* @__PURE__ */ jsxs("section", {
+			/* @__PURE__ */ jsx(OperationHeader, { operation: resolved.operation }),
+			resolved.parameters.length > 0 && /* @__PURE__ */ jsxs("section", {
 				"data-parameters": true,
 				children: [/* @__PURE__ */ jsx("h4", { children: "Parameters" }), /* @__PURE__ */ jsx(ParameterList, {
-					parameters: params,
+					parameters: resolved.parameters,
 					rootDoc,
-					meta
+					meta,
+					widgets
 				})]
 			}),
-			requestBody?.schema !== void 0 && /* @__PURE__ */ jsxs("section", {
+			resolved.requestBody?.schema !== void 0 && /* @__PURE__ */ jsxs("section", {
 				"data-request-body": true,
 				children: [
-					/* @__PURE__ */ jsxs("h4", { children: ["Request Body", requestBody.required && /* @__PURE__ */ jsx("span", {
+					/* @__PURE__ */ jsxs("h4", { children: ["Request Body", resolved.requestBody.required && /* @__PURE__ */ jsx("span", {
 						"data-required": true,
 						children: "*"
 					})] }),
-					requestBody.description && /* @__PURE__ */ jsx("p", { children: requestBody.description }),
-					requestBody.contentTypes.length > 0 && /* @__PURE__ */ jsx("span", {
+					resolved.requestBody.description && /* @__PURE__ */ jsx("p", { children: resolved.requestBody.description }),
+					resolved.requestBody.contentTypes.length > 0 && /* @__PURE__ */ jsx("span", {
 						"data-content-type": true,
-						children: requestBody.contentTypes[0]
+						children: resolved.requestBody.contentTypes[0]
 					}),
-					renderSchema(requestBody.schema, rootDoc, {
+					renderSchema(resolved.requestBody.schema, rootDoc, {
 						value: requestBodyValue,
 						onChange: onRequestBodyChange,
 						fields: requestBodyFields,
-						meta
+						meta,
+						widgets
 					})
 				]
 			}),
-			responses.length > 0 && /* @__PURE__ */ jsxs("section", {
+			resolved.responses.length > 0 && /* @__PURE__ */ jsxs("section", {
 				"data-responses": true,
-				children: [/* @__PURE__ */ jsx("h4", { children: "Responses" }), responses.map((response) => /* @__PURE__ */ jsx(ResponseCard, {
+				children: [/* @__PURE__ */ jsx("h4", { children: "Responses" }), resolved.responses.map((response) => /* @__PURE__ */ jsx(ResponseCard, {
 					response,
 					rootDoc,
 					value: responseValue,
-					meta
+					meta,
+					widgets
 				}, response.statusCode))]
 			})
 		]
 	});
 }
-function ApiParameters({ schema: doc, path, method, meta, overrides }) {
-	const parsed = getParsed(toDoc(doc));
+function ApiParameters({ schema: doc, path, method, meta, overrides, widgets }) {
 	const rootDoc = toDoc(doc);
-	const params = getParameters(parsed, path, method);
+	const params = resolveParameters(rootDoc, path, method);
 	if (params.length === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
 		"data-parameters": true,
@@ -104,14 +90,14 @@ function ApiParameters({ schema: doc, path, method, meta, overrides }) {
 			parameters: params,
 			rootDoc,
 			overrides,
-			meta
+			meta,
+			widgets
 		})]
 	});
 }
-function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields }) {
-	const parsed = getParsed(toDoc(doc));
+function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields, widgets }) {
 	const rootDoc = toDoc(doc);
-	const requestBody = getRequestBody(parsed, path, method);
+	const requestBody = resolveRequestBody(rootDoc, path, method);
 	if (requestBody?.schema === void 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
 		"data-request-body": true,
@@ -129,16 +115,15 @@ function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fiel
 				value,
 				onChange,
 				fields,
-				meta
+				meta,
+				widgets
 			})
 		]
 	});
 }
-function ApiResponse({ schema: doc, path, method, status, value, meta, fields }) {
-	const parsed = getParsed(toDoc(doc));
+function ApiResponse({ schema: doc, path, method, status, value, meta, fields, widgets }) {
 	const rootDoc = toDoc(doc);
-	const response = getResponses(parsed, path, method).find((r) => r.statusCode === status);
-	if (response === void 0) throw new SchemaNormalisationError(`Response not found: ${status}`, doc, "openapi-invalid");
+	const response = resolveResponse(rootDoc, path, method, status);
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
 		"data-status": status,
 		children: [
@@ -152,7 +137,8 @@ function ApiResponse({ schema: doc, path, method, status, value, meta, fields })
 		rootDoc,
 		value,
 		fields,
-		meta
+		meta,
+		widgets
 	});
 }
 function OperationHeader({ operation }) {
@@ -169,7 +155,7 @@ function OperationHeader({ operation }) {
 		})
 	] });
 }
-function ParameterList({ parameters, rootDoc, overrides, meta }) {
+function ParameterList({ parameters, rootDoc, overrides, meta, widgets }) {
 	return /* @__PURE__ */ jsx(Fragment, { children: parameters.map((param) => /* @__PURE__ */ jsxs("div", {
 		"data-parameter": param.name,
 		children: [
@@ -181,11 +167,14 @@ function ParameterList({ parameters, rootDoc, overrides, meta }) {
 				"data-description": true,
 				children: param.description
 			}),
-			renderSchema(param.schema ?? { type: "string" }, rootDoc, { meta: buildParamMeta(param, overrides, meta) })
+			renderSchema(param.schema ?? { type: "string" }, rootDoc, {
+				meta: buildParamMeta(param, overrides, meta),
+				widgets
+			})
 		]
 	}, param.name)) });
 }
-function ResponseCard({ response, rootDoc, value, fields, meta }) {
+function ResponseCard({ response, rootDoc, value, fields, meta, widgets }) {
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
 		"data-status": response.statusCode,
 		children: [
@@ -205,7 +194,8 @@ function ResponseCard({ response, rootDoc, value, fields, meta }) {
 				meta: {
 					readOnly: true,
 					...meta
-				}
+				},
+				widgets
 			})
 		]
 	});

package/dist/openapi/resolve.d.mts

@@ -0,0 +1,42 @@
+import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequestBody } from "./parser.mjs";
+
+//#region src/openapi/resolve.d.ts
+/**
+ * Parse and cache an OpenAPI document. Returns cached version if
+ * the same object identity has been seen before.
+ */
+declare function getParsed(doc: Record<string, unknown>): OpenApiDocument;
+/**
+ * Coerce an unknown value to a record, returning an empty record
+ * for non-objects.
+ */
+declare function toDoc(value: unknown): Record<string, unknown>;
+interface ResolvedOperation {
+  operation: OperationInfo;
+  parameters: ParameterInfo[];
+  requestBody: ReturnType<typeof getRequestBody>;
+  responses: ResponseInfo[];
+}
+/**
+ * Resolve an operation from an OpenAPI document by path and method.
+ * Throws if the operation is not found.
+ */
+declare function resolveOperation(doc: Record<string, unknown>, path: string, method: string): ResolvedOperation;
+/**
+ * Resolve parameters for an operation. Returns empty array if none.
+ */
+declare function resolveParameters(doc: Record<string, unknown>, path: string, method: string): ParameterInfo[];
+/**
+ * Resolve request body for an operation. Returns undefined if none.
+ */
+declare function resolveRequestBody(doc: Record<string, unknown>, path: string, method: string): ReturnType<typeof getRequestBody>;
+/**
+ * Resolve a specific response by status code. Throws if not found.
+ */
+declare function resolveResponse(doc: Record<string, unknown>, path: string, method: string, statusCode: string): ResponseInfo;
+/**
+ * Resolve all responses for an operation.
+ */
+declare function resolveResponses(doc: Record<string, unknown>, path: string, method: string): ResponseInfo[];
+//#endregion
+export { ResolvedOperation, getParsed, resolveOperation, resolveParameters, resolveRequestBody, resolveResponse, resolveResponses, toDoc };

package/dist/openapi/resolve.mjs

@@ -0,0 +1,72 @@
+import { isObject } from "../core/guards.mjs";
+import { getParameters, getRequestBody, getResponses, listOperations, parseOpenApiDocument } from "./parser.mjs";
+//#region src/openapi/resolve.ts
+/**
+* OpenAPI document resolution and caching.
+*
+* Pure functions for looking up operations, parameters, request bodies,
+* and responses from parsed OpenAPI documents. Extracted from components
+* for testability without React.
+*/
+const docCache = /* @__PURE__ */ new WeakMap();
+/**
+* Parse and cache an OpenAPI document. Returns cached version if
+* the same object identity has been seen before.
+*/
+function getParsed(doc) {
+	const cached = docCache.get(doc);
+	if (cached !== void 0) return cached;
+	const parsed = parseOpenApiDocument(doc);
+	docCache.set(doc, parsed);
+	return parsed;
+}
+/**
+* Coerce an unknown value to a record, returning an empty record
+* for non-objects.
+*/
+function toDoc(value) {
+	return isObject(value) ? value : {};
+}
+/**
+* Resolve an operation from an OpenAPI document by path and method.
+* Throws if the operation is not found.
+*/
+function resolveOperation(doc, path, method) {
+	const parsed = getParsed(doc);
+	const operation = listOperations(parsed).find((op) => op.path === path && op.method === method);
+	if (operation === void 0) throw new Error(`Operation not found: ${method.toUpperCase()} ${path}`);
+	return {
+		operation,
+		parameters: getParameters(parsed, path, method),
+		requestBody: getRequestBody(parsed, path, method),
+		responses: getResponses(parsed, path, method)
+	};
+}
+/**
+* Resolve parameters for an operation. Returns empty array if none.
+*/
+function resolveParameters(doc, path, method) {
+	return getParameters(getParsed(doc), path, method);
+}
+/**
+* Resolve request body for an operation. Returns undefined if none.
+*/
+function resolveRequestBody(doc, path, method) {
+	return getRequestBody(getParsed(doc), path, method);
+}
+/**
+* Resolve a specific response by status code. Throws if not found.
+*/
+function resolveResponse(doc, path, method, statusCode) {
+	const response = getResponses(getParsed(doc), path, method).find((r) => r.statusCode === statusCode);
+	if (response === void 0) throw new Error(`Response not found: ${statusCode}`);
+	return response;
+}
+/**
+* Resolve all responses for an operation.
+*/
+function resolveResponses(doc, path, method) {
+	return getResponses(getParsed(doc), path, method);
+}
+//#endregion
+export { getParsed, resolveOperation, resolveParameters, resolveRequestBody, resolveResponse, resolveResponses, toDoc };

package/dist/react/SchemaComponent.d.mts

@@ -5,13 +5,33 @@ import { ReactNode } from "react";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/react/SchemaComponent.d.ts
+/**
+ * Widget map — maps component hints (from `.meta({ component })`) to render
+ * functions. Scoped at three levels:
+ *
+ * 1. **Per-instance** — `widgets` prop on `<SchemaComponent>`
+ * 2. **Context-scoped** — `widgets` prop on `<SchemaProvider>`
+ * 3. **Global** — `registerWidget()` (app-wide defaults)
+ *
+ * Resolution order: instance → context → global → resolver → headless.
+ */
+type WidgetMap = ReadonlyMap<string, (props: RenderProps) => unknown>;
 declare function SchemaProvider({
   resolver,
+  widgets,
   children
 }: {
-  resolver: ComponentResolver;
+  resolver: ComponentResolver; /** Scoped widgets available to all SchemaComponents in this subtree. */
+  widgets?: WidgetMap;
   children: ReactNode;
 }): _$react_jsx_runtime0.JSX.Element;
+/**
+ * Register a widget globally. The widget is resolved when a schema field
+ * has `.meta({ component: name })`.
+ *
+ * For scoped registration, use the `widgets` prop on `<SchemaComponent>`
+ * or `<SchemaProvider>` instead.
+ */
 declare function registerWidget(name: string, render: (props: RenderProps) => unknown): void;
 type InferFields<T, Ref extends string | undefined> = T extends z.ZodType ? FieldOverrides<z.infer<T>> : T extends {
   openapi: unknown;
@@ -41,6 +61,8 @@ interface SchemaComponentProps<T = unknown, Ref extends string | undefined = und
   writeOnly?: boolean;
   /** Convenience: sets description on the root. */
   description?: string;
+  /** Instance-scoped widgets — override context and global widgets. */
+  widgets?: WidgetMap;
 }
 declare function SchemaComponent<T = unknown, Ref extends string | undefined = undefined>({
   schema: schemaInput,
@@ -54,9 +76,10 @@ declare function SchemaComponent<T = unknown, Ref extends string | undefined = u
   meta: componentMeta,
   readOnly,
   writeOnly,
-  description
+  description,
+  widgets: instanceWidgets
 }: SchemaComponentProps<T, Ref>): ReactNode;
-declare function renderField(tree: WalkedField, value: unknown, onChange: (v: unknown) => void, userResolver: ComponentResolver | undefined, renderChild: (tree: WalkedField, value: unknown, onChange: (v: unknown) => void) => ReactNode): ReactNode;
+declare function renderField(tree: WalkedField, value: unknown, onChange: (v: unknown) => void, userResolver: ComponentResolver | undefined, renderChild: (tree: WalkedField, value: unknown, onChange: (v: unknown) => void) => ReactNode, instanceWidgets?: WidgetMap, contextWidgets?: WidgetMap): ReactNode;
 /**
  * Infer the schema's output type for SchemaField path inference.
  */
@@ -93,4 +116,4 @@ declare function SchemaField<T = unknown, Ref extends string | undefined = undef
   onValidationError
 }: SchemaFieldProps<T, Ref, P>): ReactNode;
 //#endregion
-export { SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, registerWidget, renderField };
+export { SchemaComponent, SchemaComponentProps, SchemaField, SchemaFieldProps, SchemaProvider, WidgetMap, registerWidget, renderField };

package/dist/react/SchemaComponent.mjs

@@ -23,18 +23,31 @@ import { jsx } from "react/jsx-runtime";
 * - Runtime schemas → Record<string, FieldOverride> (no autocomplete)
 */
 const UserResolverContext = createContext(void 0);
-function SchemaProvider({ resolver, children }) {
+const WidgetsContext = createContext(void 0);
+function SchemaProvider({ resolver, widgets, children }) {
 	return /* @__PURE__ */ jsx(UserResolverContext.Provider, {
 		value: resolver,
-		children
+		children: /* @__PURE__ */ jsx(WidgetsContext.Provider, {
+			value: widgets,
+			children
+		})
 	});
 }
-const widgetRegistry = /* @__PURE__ */ new Map();
+/** Global widget registry — app-wide defaults. */
+const globalWidgets = /* @__PURE__ */ new Map();
+/**
+* Register a widget globally. The widget is resolved when a schema field
+* has `.meta({ component: name })`.
+*
+* For scoped registration, use the `widgets` prop on `<SchemaComponent>`
+* or `<SchemaProvider>` instead.
+*/
 function registerWidget(name, render) {
-	widgetRegistry.set(name, render);
+	globalWidgets.set(name, render);
 }
-function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange, validate, onValidationError, onError, fields, meta: componentMeta, readOnly, writeOnly, description }) {
+function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange, validate, onValidationError, onError, fields, meta: componentMeta, readOnly, writeOnly, description, widgets: instanceWidgets }) {
 	const userResolver = useContext(UserResolverContext);
+	const contextWidgets = useContext(WidgetsContext);
 	const mergedMeta = useMemo(() => {
 		const merged = { ...componentMeta };
 		if (readOnly === true) merged.readOnly = true;
@@ -82,9 +95,9 @@ function SchemaComponent({ schema: schemaInput, ref: refInput, value, onChange,
 		rootDocument
 	});
 	const renderChild = (childTree, childValue, childOnChange) => {
-		return renderField(childTree, childValue, childOnChange, userResolver, renderChild);
+		return renderField(childTree, childValue, childOnChange, userResolver, renderChild, instanceWidgets, contextWidgets);
 	};
-	return renderField(tree, value ?? tree.defaultValue, handleChange, userResolver, renderChild);
+	return renderField(tree, value ?? tree.defaultValue, handleChange, userResolver, renderChild, instanceWidgets, contextWidgets);
 }
 function runValidation(zodSchema, jsonSchema, value, onError) {
 	if (zodSchema !== void 0 && isObject(zodSchema)) {
@@ -107,10 +120,10 @@ function runValidation(zodSchema, jsonSchema, value, onError) {
 		}
 	}
 }
-function renderField(tree, value, onChange, userResolver, renderChild) {
+function renderField(tree, value, onChange, userResolver, renderChild, instanceWidgets, contextWidgets) {
 	const componentHint = tree.meta.component;
 	if (typeof componentHint === "string") {
-		const widget = widgetRegistry.get(componentHint);
+		const widget = instanceWidgets?.get(componentHint) ?? contextWidgets?.get(componentHint) ?? globalWidgets.get(componentHint);
 		if (widget !== void 0) {
 			const result = widget(buildRenderProps(tree, value, onChange, renderChild));
 			if (result !== void 0 && result !== null) {
@@ -160,6 +173,7 @@ function buildRenderProps(tree, value, onChange, renderChild) {
 }
 function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange, meta: fieldMeta, validate, onValidationError }) {
 	const userResolver = useContext(UserResolverContext);
+	const contextWidgets = useContext(WidgetsContext);
 	let jsonSchema;
 	let zodSchema;
 	let rootMeta;
@@ -197,9 +211,9 @@ function SchemaField({ path, schema: schemaInput, ref: refInput, value, onChange
 		onValidationError
 	]);
 	const renderChild = (childTree, childValue, childOnChange) => {
-		return renderField(childTree, childValue, childOnChange, userResolver, renderChild);
+		return renderField(childTree, childValue, childOnChange, userResolver, renderChild, void 0, contextWidgets);
 	};
-	return renderField(fieldTree, fieldValue, handleChange, userResolver, renderChild);
+	return renderField(fieldTree, fieldValue, handleChange, userResolver, renderChild, void 0, contextWidgets);
 }
 function resolvePath(tree, path) {
 	if (path.length === 0) return tree;

package/dist/react/SchemaView.d.mts

@@ -1,4 +1,5 @@
 import { b as ComponentResolver, m as SchemaMeta } from "../types-DDCD6Xnx.mjs";
+import { WidgetMap } from "./SchemaComponent.mjs";
 import { ReactNode } from "react";
 
 //#region src/react/SchemaView.d.ts
@@ -21,6 +22,8 @@ interface SchemaViewProps {
    * Falls back to the headless resolver if omitted.
    */
   resolver?: ComponentResolver;
+  /** Instance-scoped widgets. */
+  widgets?: WidgetMap;
 }
 /**
  * Server-safe schema renderer — no hooks, no context, no state.
@@ -35,7 +38,8 @@ declare function SchemaView({
   fields,
   meta: componentMeta,
   description,
-  resolver
+  resolver,
+  widgets
 }: SchemaViewProps): ReactNode;
 //#endregion
 export { SchemaView, SchemaViewProps };

package/dist/react/SchemaView.mjs

@@ -37,7 +37,7 @@ function noop() {}
 * Always renders in read-only mode. For editable forms, use
 * `<SchemaComponent>` with `"use client"`.
 */
-function SchemaView({ schema: schemaInput, ref: refInput, value, fields, meta: componentMeta, description, resolver }) {
+function SchemaView({ schema: schemaInput, ref: refInput, value, fields, meta: componentMeta, description, resolver, widgets }) {
 	const mergedMeta = {
 		...componentMeta,
 		readOnly: true
@@ -61,10 +61,31 @@ function SchemaView({ schema: schemaInput, ref: refInput, value, fields, meta: c
 		rootDocument
 	});
 	const userResolver = resolver !== void 0 ? mergeResolvers(resolver, headlessResolver) : headlessResolver;
-	const renderChild = (childTree, childValue) => renderFieldServer(childTree, childValue, userResolver, renderChild);
-	return renderFieldServer(tree, value ?? tree.defaultValue, userResolver, renderChild);
+	const renderChild = (childTree, childValue) => renderFieldServer(childTree, childValue, userResolver, renderChild, widgets);
+	return renderFieldServer(tree, value ?? tree.defaultValue, userResolver, renderChild, widgets);
 }
-function renderFieldServer(tree, value, resolver, renderChild) {
+function renderFieldServer(tree, value, resolver, renderChild, widgets) {
+	const componentHint = tree.meta.component;
+	if (typeof componentHint === "string") {
+		const widget = widgets?.get(componentHint);
+		if (widget !== void 0) {
+			const result = widget({
+				value,
+				onChange: noop,
+				readOnly: true,
+				writeOnly: false,
+				meta: tree.meta,
+				constraints: tree.constraints,
+				path: "",
+				tree,
+				renderChild: (childTree, childValue) => renderChild(childTree, childValue)
+			});
+			if (result !== void 0 && result !== null) {
+				if (isValidElement(result)) return result;
+				if (typeof result === "string" || typeof result === "number") return result;
+			}
+		}
+	}
 	const renderFn = getRenderFunction(tree.type, resolver);
 	if (renderFn !== void 0) {
 		const props = {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "schema-components",
-    "version": "1.3.2",
+    "version": "1.4.0",
     "description": "React components that render UI from Zod schemas, JSON Schema, and OpenAPI documents",
     "type": "module",
     "main": "./dist/index.mjs",