@mostra/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @mostra/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The client runtime of [Mostra](https://github.com/mostra-dev/mostra), the agent artifact runtime.
+Artifacts import it for `defineArtifact`, the manifest an artifact declares in its entry:
+
+```tsx
+import { defineArtifact } from "@mostra/react";
+
+export const artifact = defineArtifact({ title: "Sidebar options", family: "review" });
+
+export default function Page() {
+  return <h1>Sidebar options</h1>;
+}
+```
+
+Artifacts don't install it: every Mostra build resolves it from the warm set. Fields, submissions,
+actions and live data arrive in later releases. Apache-2.0.

package/dist/form.d.ts

@@ -0,0 +1,20 @@
+import { FieldPath, FieldValues, UseFormProps, UseFormReturn } from "react-hook-form";
+//#region src/form.d.ts
+/** Options of {@link useForm}: react-hook-form's, and the form's field ID. */
+export interface MostraFormOptions<TFieldValues extends FieldValues> extends Omit<UseFormProps<TFieldValues>, "values"> {
+  /** The field ID every field of the form is persisted under: `<id>.<name>` (D52). */
+  readonly id: string;
+  /** Labels for results and the shell's blockers, by field name. */
+  readonly labels?: Readonly<Partial<Record<FieldPath<TFieldValues>, string>>>;
+  /** `viewer` (default): the viewer's draft. `artifact`: shared state (D63). */
+  readonly scope?: "viewer" | "artifact";
+  /** Field names kept out of events and logs (D52), still delivered with the submission. */
+  readonly sensitive?: readonly FieldPath<TFieldValues>[];
+}
+/**
+ * react-hook-form's `useForm`, persisted to Mostra fields under `id` (D52). Everything else is
+ * react-hook-form's own: `register`, `handleSubmit`, `formState`, resolvers.
+ */
+export declare function useForm<TFieldValues extends FieldValues = FieldValues>(options: MostraFormOptions<TFieldValues>): UseFormReturn<TFieldValues>;
+//#endregion
+//# sourceMappingURL=form.d.ts.map

package/dist/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","names":[],"sources":["../src/form.ts"],"mappings":";;;iBA8EiB,kBAAkB,qBAAqB,qBAC9C,KAAK,aAAa;;WAEjB;;WAEA,SAAS,SAAS,QAAQ,OAAO,UAAU;;WAE3C;;WAEA,qBAAqB,UAAU;;;;;;wBAO1B,QAAQ,qBAAqB,cAAc,aACzD,SAAS,kBAAkB,gBAC1B,cAAc"}

package/dist/form.js

@@ -0,0 +1,259 @@
+"use client";
+import { g as fieldKey, o as useStore } from "./hooks-Dh_l8KqJ.js";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { get, set, useForm as useForm$1 } from "react-hook-form";
+//#region src/form.ts
+/**
+* `@mostra/react/form`: react-hook-form on Mostra fields (D52, D26). `useForm` is react-hook-form's
+* own, with one more option, `id`: every answer persists as the Mostra field `<id>.<path>` (a
+* field array as one answer, `<id>.items`), so a large form saves as the viewer types, resets
+* included, survives reloads and other tabs, converges with other writers, and arrives in
+* results nested under `id`. Its `required` rules and validation errors become the shell's
+* blockers.
+*
+* ```tsx
+* import { useForm } from "@mostra/react/form";
+*
+* const form = useForm({ id: "intake", defaultValues: { name: "", team: "" }, labels: { name: "Your name" } });
+* <input {...form.register("name", { required: true })} />
+* ```
+*/
+/** Whether two JSON values are the same. */
+function sameJson(a, b) {
+	return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+/** Whether a value is a plain object, whose keys the form's values nest by. */
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* A form's answers as Mostra fields (Claude review finding 1): one field per leaf, where a leaf is
+* any value that isn't a plain object, arrays included. A field array is one answer, so a row
+* removed is gone from that answer, never left behind as a field of its own, and `items` and
+* `items.1` never both exist.
+*/
+function leaves(values, path = "", out = /* @__PURE__ */ new Map()) {
+	if (isPlainObject(values)) for (const [key, value] of Object.entries(values)) leaves(value, path === "" ? key : `${path}.${key}`, out);
+	else if (path !== "") out.set(path, values);
+	return out;
+}
+/** The leaf a registered name lives in: the name itself, or the array it is inside. */
+function leafOf(values, name) {
+	const parts = name.split(".");
+	let current = values;
+	for (let index = 0; index < parts.length; index += 1) {
+		if (Array.isArray(current)) return parts.slice(0, index).join(".");
+		if (!isPlainObject(current)) return name;
+		current = current[parts[index]];
+	}
+	return name;
+}
+/**
+* react-hook-form's `useForm`, persisted to Mostra fields under `id` (D52). Everything else is
+* react-hook-form's own: `register`, `handleSubmit`, `formState`, resolvers.
+*/
+function useForm(options) {
+	const store = useStore();
+	const { id, labels, scope = "viewer", sensitive, ...hookOptions } = options;
+	const prefix = `${id}.`;
+	const version = useSyncExternalStore(store.subscribe, store.version, store.version);
+	const [defaults] = useState(() => hookOptions.defaultValues);
+	const defaultOf = useCallback((leaf) => get(defaults ?? {}, leaf), [defaults]);
+	const storedValue = useCallback((leaf) => store.value(fieldKey(scope, `${prefix}${leaf}`), defaultOf(leaf)), [
+		store,
+		scope,
+		prefix,
+		defaultOf
+	]);
+	const stored = useCallback((leaf) => store.value(fieldKey(scope, `${prefix}${leaf}`), void 0) !== void 0, [
+		store,
+		scope,
+		prefix
+	]);
+	const [initial] = useState(() => {
+		const base = typeof defaults === "object" && defaults !== null ? structuredClone(defaults) : {};
+		for (const fieldId of store.ids(scope)) {
+			if (!fieldId.startsWith(prefix)) continue;
+			set(base, fieldId.slice(prefix.length), store.value(fieldKey(scope, fieldId), void 0));
+		}
+		return base;
+	});
+	const form = useForm$1({
+		...hookOptions,
+		defaultValues: initial
+	});
+	const labelsKey = JSON.stringify(labels ?? {});
+	const stableLabels = useMemo(() => JSON.parse(labelsKey), [labelsKey]);
+	const sensitiveNames = useMemo(() => new Set(sensitive ?? []), [sensitive]);
+	const save = useCallback((values) => {
+		const current = leaves(values);
+		for (const [leaf, value] of current) {
+			const key = fieldKey(scope, `${prefix}${leaf}`);
+			if (!store.writable(key)) continue;
+			if (stored(leaf) ? sameJson(value, storedValue(leaf)) : sameJson(value, defaultOf(leaf))) continue;
+			const label = stableLabels?.[leaf];
+			store.set(scope, `${prefix}${leaf}`, value, {
+				...label !== void 0 ? { label } : {},
+				...sensitiveNames.has(leaf) ? { sensitive: true } : {}
+			});
+		}
+	}, [
+		store,
+		scope,
+		prefix,
+		stored,
+		storedValue,
+		defaultOf,
+		stableLabels,
+		sensitiveNames
+	]);
+	useEffect(() => form.subscribe({
+		formState: { values: true },
+		callback: ({ values }) => save(values)
+	}), [form, save]);
+	const { getValues, setValue } = form;
+	useEffect(() => {
+		const current = leaves(getValues());
+		for (const [leaf, value] of current) {
+			const next = storedValue(leaf);
+			if (sameJson(next, value)) continue;
+			setValue(leaf, next, {
+				shouldDirty: false,
+				shouldTouch: false,
+				shouldValidate: false
+			});
+		}
+	}, [
+		version,
+		store,
+		scope,
+		prefix,
+		storedValue,
+		getValues,
+		setValue
+	]);
+	const rules = useRef(/* @__PURE__ */ new Map());
+	const mounted = useRef(/* @__PURE__ */ new Map());
+	const [, setReleased] = useState(0);
+	const release = useCallback((name) => {
+		rules.current.delete(name);
+		queueMicrotask(() => setReleased((count) => count + 1));
+	}, []);
+	const { register, unregister } = form;
+	const refs = useRef(/* @__PURE__ */ new Map());
+	const wrapped = useMemo(() => ((name, ruleOptions) => {
+		const required = ruleOptions?.required !== void 0 && ruleOptions.required !== false;
+		rules.current.set(name, required);
+		const registered = register(name, ruleOptions);
+		let entry = refs.current.get(name);
+		if (!entry) {
+			const created = {
+				latest: registered.ref,
+				ref: (element) => {
+					created.latest(element);
+					if (element === null) release(name);
+					else rules.current.set(name, rules.current.get(name) ?? required);
+				}
+			};
+			entry = created;
+			refs.current.set(name, entry);
+		}
+		entry.latest = registered.ref;
+		return {
+			...registered,
+			ref: entry.ref
+		};
+	}), [register, release]);
+	const wrappedUnregister = useMemo(() => ((name, options) => {
+		const names = name === void 0 ? [...rules.current.keys()] : Array.isArray(name) ? name : [name];
+		for (const each of names) release(each);
+		unregister(name, options);
+	}), [unregister, release]);
+	const errors = form.formState.errors;
+	const sync = useCallback((errorOf) => {
+		const values = getValues();
+		const byLeaf = /* @__PURE__ */ new Map();
+		for (const [name, required] of rules.current) {
+			const leaf = leafOf(values, name);
+			const failure = errorOf(name);
+			const message = failure === void 0 ? void 0 : typeof failure.message === "string" && failure.message !== "" ? failure.message : required ? "This answer is required." : "Invalid value.";
+			const entry = byLeaf.get(leaf) ?? { required: false };
+			if (leaf === name && required) entry.required = true;
+			if (entry.message === void 0 && message !== void 0) entry.message = message;
+			byLeaf.set(leaf, entry);
+		}
+		for (const [leaf, { required, message }] of byLeaf) {
+			const fieldId = `${prefix}${leaf}`;
+			const label = stableLabels?.[leaf];
+			const registration = {
+				id: fieldId,
+				scope,
+				hook: "useForm",
+				initial: defaultOf(leaf),
+				...label !== void 0 ? { label } : {},
+				...required ? { required } : {},
+				...sensitiveNames.has(leaf) ? { sensitive: true } : {},
+				...message !== void 0 ? { error: message } : {}
+			};
+			const signature = JSON.stringify([
+				label,
+				required,
+				sensitiveNames.has(leaf),
+				message
+			]);
+			const current = mounted.current.get(fieldId);
+			if (!current) {
+				mounted.current.set(fieldId, {
+					release: store.register(registration),
+					signature
+				});
+				if (message !== void 0) store.updateRegistration(registration);
+			} else if (current.signature !== signature) {
+				current.signature = signature;
+				store.updateRegistration(registration);
+			}
+		}
+		for (const [fieldId, entry] of mounted.current) {
+			if (byLeaf.has(fieldId.slice(prefix.length))) continue;
+			entry.release();
+			mounted.current.delete(fieldId);
+		}
+	}, [
+		prefix,
+		scope,
+		stableLabels,
+		sensitiveNames,
+		store,
+		defaultOf,
+		getValues
+	]);
+	useEffect(() => sync((name) => get(errors, name)));
+	const { trigger, getFieldState } = form;
+	useEffect(() => store.beforeSubmit(async () => {
+		save(getValues());
+		await trigger();
+		sync((name) => getFieldState(name).error);
+	}), [
+		store,
+		trigger,
+		getFieldState,
+		sync,
+		save,
+		getValues
+	]);
+	useEffect(() => () => {
+		for (const entry of mounted.current.values()) entry.release();
+		mounted.current.clear();
+	}, []);
+	return {
+		...form,
+		register: wrapped,
+		unregister: wrappedUnregister
+	};
+}
+//#endregion
+export { useForm };
+
+//# sourceMappingURL=form.js.map

package/dist/form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.js","names":["useHookForm"],"sources":["../src/form.ts"],"sourcesContent":["\"use client\";\n\n/**\n * `@mostra/react/form`: react-hook-form on Mostra fields (D52, D26). `useForm` is react-hook-form's\n * own, with one more option, `id`: every answer persists as the Mostra field `<id>.<path>` (a\n * field array as one answer, `<id>.items`), so a large form saves as the viewer types, resets\n * included, survives reloads and other tabs, converges with other writers, and arrives in\n * results nested under `id`. Its `required` rules and validation errors become the shell's\n * blockers.\n *\n * ```tsx\n * import { useForm } from \"@mostra/react/form\";\n *\n * const form = useForm({ id: \"intake\", defaultValues: { name: \"\", team: \"\" }, labels: { name: \"Your name\" } });\n * <input {...form.register(\"name\", { required: true })} />\n * ```\n */\nimport { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from \"react\";\nimport {\n  type FieldPath,\n  type FieldValues,\n  get,\n  type RegisterOptions,\n  set as setPath,\n  type UseFormProps,\n  type UseFormReturn,\n  useForm as useHookForm,\n} from \"react-hook-form\";\nimport { useStore } from \"./hooks.ts\";\n\n/** Whether two JSON values are the same. */\nfunction sameJson(a: unknown, b: unknown): boolean {\n  return a === b || JSON.stringify(a) === JSON.stringify(b);\n}\n\nimport { fieldKey } from \"./runtime/store.ts\";\n\n/** Whether a value is a plain object, whose keys the form's values nest by. */\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) return false;\n  const proto = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n\n/**\n * A form's answers as Mostra fields (Claude review finding 1): one field per leaf, where a leaf is\n * any value that isn't a plain object, arrays included. A field array is one answer, so a row\n * removed is gone from that answer, never left behind as a field of its own, and `items` and\n * `items.1` never both exist.\n */\nfunction leaves(\n  values: unknown,\n  path = \"\",\n  out = new Map<string, unknown>(),\n): Map<string, unknown> {\n  if (isPlainObject(values)) {\n    for (const [key, value] of Object.entries(values)) {\n      leaves(value, path === \"\" ? key : `${path}.${key}`, out);\n    }\n  } else if (path !== \"\") {\n    out.set(path, values);\n  }\n  return out;\n}\n\n/** The leaf a registered name lives in: the name itself, or the array it is inside. */\nfunction leafOf(values: unknown, name: string): string {\n  const parts = name.split(\".\");\n  let current: unknown = values;\n  for (let index = 0; index < parts.length; index += 1) {\n    if (Array.isArray(current)) return parts.slice(0, index).join(\".\");\n    if (!isPlainObject(current)) return name;\n    current = current[parts[index] as string];\n  }\n  return name;\n}\n\n/** Options of {@link useForm}: react-hook-form's, and the form's field ID. */\nexport interface MostraFormOptions<TFieldValues extends FieldValues>\n  extends Omit<UseFormProps<TFieldValues>, \"values\"> {\n  /** The field ID every field of the form is persisted under: `<id>.<name>` (D52). */\n  readonly id: string;\n  /** Labels for results and the shell's blockers, by field name. */\n  readonly labels?: Readonly<Partial<Record<FieldPath<TFieldValues>, string>>>;\n  /** `viewer` (default): the viewer's draft. `artifact`: shared state (D63). */\n  readonly scope?: \"viewer\" | \"artifact\";\n  /** Field names kept out of events and logs (D52), still delivered with the submission. */\n  readonly sensitive?: readonly FieldPath<TFieldValues>[];\n}\n\n/**\n * react-hook-form's `useForm`, persisted to Mostra fields under `id` (D52). Everything else is\n * react-hook-form's own: `register`, `handleSubmit`, `formState`, resolvers.\n */\nexport function useForm<TFieldValues extends FieldValues = FieldValues>(\n  options: MostraFormOptions<TFieldValues>,\n): UseFormReturn<TFieldValues> {\n  const store = useStore();\n  const { id, labels, scope = \"viewer\", sensitive, ...hookOptions } = options;\n  const prefix = `${id}.`;\n  const version = useSyncExternalStore(store.subscribe, store.version, store.version);\n\n  // The form starts from its answers as Mostra has them, over its defaults. After that, every\n  // answer follows the store: the store's value of a field is the viewer's own unsaved edit while\n  // there is one, else the gateway's, so another writer's change reaches the input once the\n  // viewer's edit landed, and never overwrites it before (GPT review finding 5).\n  const [defaults] = useState(() => hookOptions.defaultValues);\n  const defaultOf = useCallback((leaf: string): unknown => get(defaults ?? {}, leaf), [defaults]);\n  const storedValue = useCallback(\n    (leaf: string): unknown => store.value(fieldKey(scope, `${prefix}${leaf}`), defaultOf(leaf)),\n    [store, scope, prefix, defaultOf],\n  );\n  const stored = useCallback(\n    (leaf: string): boolean =>\n      store.value(fieldKey(scope, `${prefix}${leaf}`), undefined) !== undefined,\n    [store, scope, prefix],\n  );\n  const [initial] = useState(() => {\n    const base =\n      typeof defaults === \"object\" && defaults !== null\n        ? structuredClone(defaults as TFieldValues)\n        : ({} as TFieldValues);\n    for (const fieldId of store.ids(scope)) {\n      if (!fieldId.startsWith(prefix)) continue;\n      setPath(base, fieldId.slice(prefix.length), store.value(fieldKey(scope, fieldId), undefined));\n    }\n    return base;\n  });\n\n  const form = useHookForm<TFieldValues>({ ...hookOptions, defaultValues: initial as never });\n\n  // Labels usually come as an object literal: the same labels are the same registration.\n  const labelsKey = JSON.stringify(labels ?? {});\n  const stableLabels = useMemo(\n    () => JSON.parse(labelsKey) as MostraFormOptions<TFieldValues>[\"labels\"],\n    [labelsKey],\n  );\n  const sensitiveNames = useMemo(() => new Set<string>(sensitive ?? []), [sensitive]);\n\n  // Every change saves the answers that differ from what Mostra holds, leaf by leaf: a typed\n  // value, a row appended or removed, and a `reset()` alike, so what the viewer sees is what a\n  // submit sends (Claude review findings 1 and 2). An answer still at its default and never\n  // stored stays unstored: a default is written only before a submit (D110).\n  const save = useCallback(\n    (values: unknown): void => {\n      const current = leaves(values);\n      for (const [leaf, value] of current) {\n        const key = fieldKey(scope, `${prefix}${leaf}`);\n        if (!store.writable(key)) continue;\n        if (stored(leaf) ? sameJson(value, storedValue(leaf)) : sameJson(value, defaultOf(leaf))) {\n          continue;\n        }\n        const label = stableLabels?.[leaf as FieldPath<TFieldValues>];\n        store.set(scope, `${prefix}${leaf}`, value, {\n          ...(label !== undefined ? { label } : {}),\n          ...(sensitiveNames.has(leaf) ? { sensitive: true } : {}),\n        });\n      }\n      // A stored answer the form doesn't have is left alone: it may be an answer an earlier\n      // version asked for, which is kept and delivered as not carried over (D42).\n    },\n    [store, scope, prefix, stored, storedValue, defaultOf, stableLabels, sensitiveNames],\n  );\n  useEffect(\n    () =>\n      form.subscribe({\n        formState: { values: true },\n        callback: ({ values }) => save(values),\n      }),\n    [form, save],\n  );\n\n  // Answers that changed in the store (another writer, another tab, a snapshot) reach the form,\n  // leaf by leaf; the store's own value coming back isn't saved again (`save` finds no change).\n  const { getValues, setValue } = form;\n  // `version` stands for the store's state, which the effect reads through `store`.\n  // biome-ignore lint/correctness/useExhaustiveDependencies: as above.\n  useEffect(() => {\n    // Only the form's own answers: a stored answer it doesn't have (an earlier version's) stays\n    // out of its values.\n    const current = leaves(getValues());\n    for (const [leaf, value] of current) {\n      const next = storedValue(leaf);\n      if (sameJson(next, value)) continue;\n      setValue(leaf as FieldPath<TFieldValues>, next as never, {\n        shouldDirty: false,\n        shouldTouch: false,\n        shouldValidate: false,\n      });\n    }\n  }, [version, store, scope, prefix, storedValue, getValues, setValue]);\n\n  // Registered fields become Mostra registrations of the leaves they live in, so the shell lists\n  // their blockers. Only mounted ones: a field whose input left the page, or that `unregister`\n  // removed, is released, so it neither blocks a submit nor has its default written (D110, GPT\n  // review finding 11). A field inside a field array registers its array: its own rules run in\n  // react-hook-form, whose errors block the submit (D106).\n  const rules = useRef(new Map<string, boolean>());\n  const mounted = useRef(new Map<string, { release: () => void; signature: string }>());\n  // Bumped when a field is released: the render that follows lets its registration go.\n  const [, setReleased] = useState(0);\n  const release = useCallback((name: string): void => {\n    rules.current.delete(name);\n    // Inside React's commit (a ref callback): the store hears of it after, never re-entering it.\n    queueMicrotask(() => setReleased((count) => count + 1));\n  }, []);\n  const { register, unregister } = form;\n  // One ref callback per field, so React calls it on mount and unmount only, not every render.\n  const refs = useRef(\n    new Map<string, { latest: (element: unknown) => void; ref: (element: unknown) => void }>(),\n  );\n  const wrapped = useMemo(\n    () =>\n      ((name: FieldPath<TFieldValues>, ruleOptions?: RegisterOptions<TFieldValues>) => {\n        const required = ruleOptions?.required !== undefined && ruleOptions.required !== false;\n        rules.current.set(name, required);\n        const registered = register(name, ruleOptions);\n        let entry = refs.current.get(name);\n        if (!entry) {\n          const created = {\n            latest: registered.ref as (element: unknown) => void,\n            ref: (element: unknown): void => {\n              created.latest(element);\n              if (element === null) release(name);\n              else rules.current.set(name, rules.current.get(name) ?? required);\n            },\n          };\n          entry = created;\n          refs.current.set(name, entry);\n        }\n        entry.latest = registered.ref as (element: unknown) => void;\n        return { ...registered, ref: entry.ref };\n      }) as UseFormReturn<TFieldValues>[\"register\"],\n    [register, release],\n  );\n  const wrappedUnregister = useMemo(\n    () =>\n      ((name?: FieldPath<TFieldValues> | readonly FieldPath<TFieldValues>[], options?: never) => {\n        const names =\n          name === undefined ? [...rules.current.keys()] : Array.isArray(name) ? name : [name];\n        for (const each of names) release(each as string);\n        unregister(name as never, options);\n      }) as UseFormReturn<TFieldValues>[\"unregister\"],\n    [unregister, release],\n  );\n  const errors = form.formState.errors;\n  // Registered on the first render that names a field, updated only when a rule, label or error\n  // changes, and released when no mounted field lives in the leaf: re-registering on every\n  // render would never settle.\n  const sync = useCallback(\n    (errorOf: (name: string) => unknown): void => {\n      const values = getValues();\n      const byLeaf = new Map<string, { required: boolean; message?: string }>();\n      for (const [name, required] of rules.current) {\n        const leaf = leafOf(values, name);\n        const failure = errorOf(name) as { message?: unknown } | undefined;\n        const message =\n          failure === undefined\n            ? undefined\n            : typeof failure.message === \"string\" && failure.message !== \"\"\n              ? failure.message\n              : required\n                ? \"This answer is required.\"\n                : \"Invalid value.\";\n        const entry = byLeaf.get(leaf) ?? { required: false };\n        // A required rule inside an array is react-hook-form's to check, not the leaf's.\n        if (leaf === name && required) entry.required = true;\n        if (entry.message === undefined && message !== undefined) entry.message = message;\n        byLeaf.set(leaf, entry);\n      }\n      for (const [leaf, { required, message }] of byLeaf) {\n        const fieldId = `${prefix}${leaf}`;\n        const label = stableLabels?.[leaf as FieldPath<TFieldValues>];\n        const registration = {\n          id: fieldId,\n          scope,\n          hook: \"useForm\",\n          initial: defaultOf(leaf),\n          ...(label !== undefined ? { label } : {}),\n          ...(required ? { required } : {}),\n          ...(sensitiveNames.has(leaf) ? { sensitive: true } : {}),\n          ...(message !== undefined ? { error: message } : {}),\n        };\n        const signature = JSON.stringify([label, required, sensitiveNames.has(leaf), message]);\n        const current = mounted.current.get(fieldId);\n        if (!current) {\n          mounted.current.set(fieldId, { release: store.register(registration), signature });\n          if (message !== undefined) store.updateRegistration(registration);\n        } else if (current.signature !== signature) {\n          current.signature = signature;\n          store.updateRegistration(registration);\n        }\n      }\n      for (const [fieldId, entry] of mounted.current) {\n        if (byLeaf.has(fieldId.slice(prefix.length))) continue;\n        entry.release();\n        mounted.current.delete(fieldId);\n      }\n    },\n    [prefix, scope, stableLabels, sensitiveNames, store, defaultOf, getValues],\n  );\n  useEffect(() => sync((name) => get(errors, name)));\n  // react-hook-form validates on submit unless told otherwise; before either channel's submit\n  // it validates now, so its errors are the submit's blockers (D106: the client checks), and\n  // every answer the viewer sees is saved first.\n  const { trigger, getFieldState } = form;\n  useEffect(\n    () =>\n      store.beforeSubmit(async () => {\n        save(getValues());\n        await trigger();\n        sync((name) => getFieldState(name as FieldPath<TFieldValues>).error);\n      }),\n    [store, trigger, getFieldState, sync, save, getValues],\n  );\n  useEffect(\n    () => () => {\n      for (const entry of mounted.current.values()) entry.release();\n      mounted.current.clear();\n    },\n    [],\n  );\n\n  // A new object each render: react-hook-form renews `formState`'s proxy every render.\n  return { ...form, register: wrapped, unregister: wrappedUnregister };\n}\n"],"mappings":"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"}