@10x-media/form-builder 0.1.0-beta.11 → 0.1.0-beta.13

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @10x-media/form-builder
 
+## 0.1.0-beta.13
+
+### Patch Changes
+
+- Make the poll tally writer's Postgres import opaque to bundlers.
+
+  The optional `@payloadcms/db-postgres` peer was loaded via a literal dynamic import, which bundlers resolve at build time: a Mongo host on Turbopack failed `next build` with "Module not found" even though the Postgres branch never runs there (and `serverExternalPackages` does not help, since it governs bundling, not resolution). The specifier is now built at runtime, so no bundler resolves it and the package is only touched when the adapter is actually Postgres. Mongo hosts that worked around this with a resolve alias or stub can remove it.
+
+  Two upgrade notes from the same integrator round: hosts that had extended the select field block with their own `display` field must remove it on the beta.12 bump (the plugin ships one with identical values, and Payload refuses to boot with two same-name fields); and custom renderers replace the built-ins wholesale, so per-instance settings added in minor releases (`display` variants, `autocomplete`, calculation formatting) must be read by your renderer or an author's choice is silently ignored, now documented in the rendering guide.
+
+## 0.1.0-beta.12
+
+### Minor Changes
+
+- Authoring UX round: a visual calculation builder, display variants, an optional-by-default field config surface, and a poll vote tally store.
+
+  - **Visual calculation builder.** The calculation field's expression is authored in a native left-to-right chain editor: start with a value (Field, Number, Weighted field, Function, or a registered source), add operation steps, optionally finish with a function, with a live readable preview and honest remove affordances throughout. The stored expression tree is unchanged and any API-written expression loads as the equivalent chain; read-only and error states are wired, and field pickers only offer numeric fields (calculations restricted to earlier ones, matching evaluation order).
+  - **Calculation extensibility.** A new `calc` option opens the expression engine to host data: `calc.sources` registers named value resolvers (`resolve` returns one number per render/submission, e.g. a tax rate or member discount; `resolveWeights` returns per-option numbers for a chosen field, e.g. each selectable product's live price) that resolve server-side, ride the form document for the client preview, and re-resolve authoritatively at submit; `calc.functions` registers custom calculation functions (client previews additionally accept the same map via `<Form calcFunctions>`). The calculation field also gains display formatting (`decimals`, localized `prefix`/`suffix`) applied in the renderer, admin answers, and email output. New utilities: `defineCalcSource`, `defineCalcFunction`, `resolveCalcContext`, `formatCalc`, `formatCalcValue`, and a `useCalcValues()` hook for composed frontends reading live computed values.
+  - **Display variants.** Select fields gain an optional `display` setting (`dropdown` default, `radio`, `buttons`) rendered as an accessible radio group with the invalid-state focus routing intact; checkbox fields gain `checkbox` or `switch`. The `ChoiceGroup` primitive is exported for custom renderers.
+  - **Optional field settings.** Field width and select option labels are no longer required: width defaults to full (the renderer already falls back), and a missing or blank option label falls back to the value everywhere (renderer, admin answers, aggregation, recall). Width option labels are localized.
+  - **Sidebar form flags with a compose seam.** `multistep`, `pollEnabled`, and `persistSubmissions` are stacked sidebar checkboxes, composed through the new `settings.fields` option so a host can relocate, wrap, extend, or drop them. Forms now registers before form-submissions in the admin nav.
+  - **Advanced tab seam.** Field types can append settings to the Advanced tab via `advancedConfig`; text and email use it for an `autocomplete` autofill hint. The `hidden` flag documents that hidden fields are still validated. New `integer` validation rule for number fields; flow validation messages are localized.
+  - **Poll vote store (default on).** Votes are counted into a hidden append-only tally collection (`form-poll-votes`) when a submission completes: results reads and `mostVoted` resolution become one indexed find (no scan, no 10k truncation), tallies survive `persistSubmissions: false` and admin deletions (votes are permanent), rows are pure aggregate so a persist-off poll retains zero per-visitor data, and writes are atomic, transaction-joined, and sharded against concurrent write conflicts. `poll.votes: false` restores scan-based results and rejects persist-off polls at save. Exported: `recountPollVotes`, `aggregateFromVotes`, `POLL_VOTES_SLUG`, `RESPONDENTS_VALUE`, `VOTE_SHARDS`. Postgres hosts create the new `form_poll_votes` table with their next migration; `@10x-media/form-builder` declares `@payloadcms/db-postgres` as an optional peer for the tally write path.
+
 ## 0.1.0-beta.11
 
 ### Minor Changes

package/dist/aggregation/resolveResultsRequest.d.ts

@@ -29,6 +29,12 @@ type ResolveResultsRequestArgs = {
    * answers as leftover result buckets.
    */
   eligibleTypes?: readonly string[];
+  /**
+   * Whether the hidden tally store backs poll reads. When true, the poll results field is served
+   * from `aggregateFromVotes` (anonymous reads, and an authed read naming exactly that field)
+   * instead of the submission scan; every authorization gate stays identical either way.
+   */
+  pollVotesEnabled?: boolean;
 };
 type ResolveResultsRequestResult = {
   status: number;

package/dist/aggregation/resolveResultsRequest.js

@@ -1,8 +1,9 @@
 import { isPollClosed, pollConfigOf } from "../form/pollState.js";
 import { aggregateFormResponses, fieldHasOptions } from "./aggregateResponses.js";
+import { resolveEffectivePollOptions } from "../poll/effectivePollOptions.js";
+import { aggregateFromVotes } from "../poll/votes/aggregateFromVotes.js";
 import { resolvePollOutcome } from "../poll/resolvePollOutcome.js";
 import { shouldAutoResolvePoll } from "../poll/closeJob.js";
-import { resolveEffectivePollOptions } from "../poll/effectivePollOptions.js";
 import { FORMS_SLUG } from "../collections/forms.js";
 //#region src/aggregation/resolveResultsRequest.ts
 const forbidden = {
@@ -13,6 +14,11 @@ const unavailable = {
 	status: 503,
 	body: { errors: [{ message: "Poll options unavailable" }] }
 };
+/** Scan-shape parity for a tally-served field: label from the live instance, else the field name. */
+const tallyMetaOf = (instance, field) => ({
+	label: typeof instance?.label === "string" && instance.label.length > 0 ? instance.label : field,
+	fieldType: instance?.blockType
+});
 /**
 * Authorize and resolve a poll/survey results request. Authed callers may aggregate any field (or all
 * enumerable fields) and bypass the `access` seam; for a poll-enabled form they also get the results
@@ -29,7 +35,7 @@ const unavailable = {
 * closed (503) on the anonymous path. Returns only aggregate counts, never raw submissions.
 */
 const resolveFormResultsRequest = async (args) => {
-	const { payload, formId, field, isAuthed, req, access, eligibleTypes } = args;
+	const { payload, formId, field, isAuthed, req, access, eligibleTypes, pollVotesEnabled } = args;
 	if (formId == null) return {
 		status: 400,
 		body: { errors: [{ message: "Missing form id" }] }
@@ -48,7 +54,8 @@ const resolveFormResultsRequest = async (args) => {
 	if (shouldAutoResolvePoll(form)) await resolvePollOutcome({
 		payload,
 		formId,
-		req
+		req,
+		pollVotesEnabled
 	}).catch(() => void 0);
 	let fields;
 	let resolvedOptions;
@@ -63,6 +70,17 @@ const resolveFormResultsRequest = async (args) => {
 				form
 			}).catch(() => []);
 			if (options.length > 0) resolvedOptions = { [resultsField]: options };
+			if (pollVotesEnabled === true && field === resultsField) return {
+				status: 200,
+				body: { results: [await aggregateFromVotes({
+					payload,
+					formId,
+					field: resultsField,
+					meta: tallyMetaOf((Array.isArray(form.fields) ? form.fields : []).find((entry) => entry.name === resultsField), resultsField),
+					options: resolvedOptions?.[resultsField] ?? [],
+					req
+				})] }
+			};
 		}
 	} else {
 		const poll = pollConfigOf(form.poll);
@@ -93,6 +111,17 @@ const resolveFormResultsRequest = async (args) => {
 			return unavailable;
 		}
 		if (options.length === 0) return forbidden;
+		if (pollVotesEnabled === true) return {
+			status: 200,
+			body: { results: [await aggregateFromVotes({
+				payload,
+				formId,
+				field: publicField,
+				meta: tallyMetaOf(instance, publicField),
+				options,
+				req
+			})] }
+		};
 		resolvedOptions = { [publicField]: options };
 		fields = [publicField];
 	}

package/dist/aggregation/resolveResultsRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolveResultsRequest.js","names":[],"sources":["../../src/aggregation/resolveResultsRequest.ts"],"sourcesContent":["import type { Payload, PayloadRequest } from 'payload'\nimport { FORMS_SLUG } from '../collections/forms'\nimport { isPollClosed, pollConfigOf } from '../form/pollState'\nimport { type PollFormLike, shouldAutoResolvePoll } from '../poll/closeJob'\nimport type { PollOption } from '../poll/definePollOptionSource'\nimport { resolveEffectivePollOptions } from '../poll/effectivePollOptions'\nimport { resolvePollOutcome } from '../poll/resolvePollOutcome'\nimport type { FormFieldInstance } from '../submissions/types'\nimport { aggregateFormResponses, fieldHasOptions } from './aggregateResponses'\nimport type { FieldAggregation } from './types'\n\nexport type FormResultsAccessArgs = {\n\treq: PayloadRequest\n\t/** The loaded forms document (depth 0). Untyped beyond `id`: hosts read their own fields (e.g. `form.tenant`). */\n\tform: { id: number | string } & Record<string, unknown>\n}\n\n/**\n * Host seam gating anonymous results reads, evaluated after the form is loaded and before anything\n * is aggregated. Multi-tenant recipe: compare `form.tenant` against the tenant derived from `req`\n * (host header, cookie, or auth context) and return `false` for a cross-tenant read. Authenticated\n * callers bypass this seam (they are admin-trusted, like the rest of the results endpoint).\n */\nexport type FormResultsAccess = (args: FormResultsAccessArgs) => boolean | Promise<boolean>\n\nexport type ResolveResultsRequestArgs = {\n\tpayload: Payload\n\tformId: number | string | undefined\n\t/** The requested field (query param). */\n\tfield?: string\n\t/** Whether the caller is authenticated (an admin/user). */\n\tisAuthed: boolean\n\treq?: PayloadRequest\n\t/** Optional host seam for anonymous reads; absent means plugin-default gating only. */\n\taccess?: FormResultsAccess\n\t/**\n\t * Poll-eligible field types (registry-derived). When set, an anonymous read of an\n\t * option-source poll also requires the results field's instance to be one of these types,\n\t * so legacy or db-written docs pointing at a free-text field can never expose stored\n\t * answers as leftover result buckets.\n\t */\n\teligibleTypes?: readonly string[]\n}\n\nexport type ResolveResultsRequestResult = {\n\tstatus: number\n\tbody: { results: FieldAggregation[] } | { errors: { message: string }[] }\n}\n\nconst forbidden: ResolveResultsRequestResult = {\n\tstatus: 403,\n\tbody: { errors: [{ message: 'Forbidden' }] },\n}\n\n// 503 over 403 for a failed option-source resolve: the form and its poll config are already\n// publicly readable, so \"temporarily unavailable\" leaks nothing new, matches the submission\n// path's precedent, and does not mislabel a transient server fault as an authorization denial.\nconst unavailable: ResolveResultsRequestResult = {\n\tstatus: 503,\n\tbody: { errors: [{ message: 'Poll options unavailable' }] },\n}\n\n/**\n * Authorize and resolve a poll/survey results request. Authed callers may aggregate any field (or all\n * enumerable fields) and bypass the `access` seam; for a poll-enabled form they also get the results\n * field's effective options injected so sourced/resolver-backed polls render labels (best-effort, a\n * resolve failure degrades to raw values rather than blocking the trusted read). Anonymous callers are\n * allowed only when the form's poll is enabled, the poll's `resultsVisibility` permits it (`afterVote`:\n * any time; `afterClose`: only once `closesAt` has passed), and the optional host `access` seam\n * approves; and then only for the configured `poll.resultsField`, and only if that field is enumerable\n * so a misconfigured `resultsField` pointing at a free-text or PII field can never be dumped publicly. A\n * static poll is enumerable through its authored options; a poll whose options come from an\n * `optionSource` or the field type's own `resolveOptions` resolves them here (registry via\n * `config.custom`, per-request cache), gated by `eligibleTypes` and enumerable only when resolution\n * yields any, with the resolved options driving bucket order and labels. Resolution failure fails\n * closed (503) on the anonymous path. Returns only aggregate counts, never raw submissions.\n */\nexport const resolveFormResultsRequest = async (\n\targs: ResolveResultsRequestArgs\n): Promise<ResolveResultsRequestResult> => {\n\tconst { payload, formId, field, isAuthed, req, access, eligibleTypes } = args\n\tif (formId == null) {\n\t\treturn { status: 400, body: { errors: [{ message: 'Missing form id' }] } }\n\t}\n\tconst form = await payload\n\t\t.findByID({ collection: FORMS_SLUG, id: formId, depth: 0, overrideAccess: true, req })\n\t\t.catch(() => null)\n\tif (!form) {\n\t\treturn { status: 404, body: { errors: [{ message: 'Not found' }] } }\n\t}\n\n\t// No-runner safety net: when a closed poll's `mostVoted`/`source` outcome was never auto-resolved\n\t// (no wired job runner fired the close task), a results read heals it. Idempotent and gate-neutral,\n\t// it runs on the already-loaded form via overrideAccess and writes only through the outcome hook, so\n\t// it cannot relax the anonymous authorization below. A failure degrades silently to the normal path.\n\tif (shouldAutoResolvePoll(form as PollFormLike)) {\n\t\tawait resolvePollOutcome({ payload, formId, req }).catch(() => undefined)\n\t}\n\n\tlet fields: string[] | undefined\n\tlet resolvedOptions: Record<string, { value: string; label: string }[]> | undefined\n\tif (isAuthed) {\n\t\tfields = field ? [field] : undefined\n\t\t// Label a poll's results field for admins: resolve its effective options (a source, the\n\t\t// field type's own resolver, or authored options) and inject them so a sourced/resolved poll\n\t\t// shows labels instead of raw stored values, and so an all-fields read still surfaces a\n\t\t// resolver-backed field that carries no authored options. Best-effort: a resolver/source\n\t\t// failure degrades to raw values rather than blocking the trusted read (the anonymous path\n\t\t// below fails closed instead). Only run when the read would actually surface the results field.\n\t\tconst poll = pollConfigOf(form.poll)\n\t\tconst resultsField =\n\t\t\ttypeof poll?.resultsField === 'string' && poll.resultsField.length > 0\n\t\t\t\t? poll.resultsField\n\t\t\t\t: undefined\n\t\tif (form.pollEnabled === true && resultsField && (!field || field === resultsField)) {\n\t\t\tconst options: PollOption[] = await resolveEffectivePollOptions({\n\t\t\t\tpayload,\n\t\t\t\treq,\n\t\t\t\tform,\n\t\t\t}).catch(() => [])\n\t\t\tif (options.length > 0) {\n\t\t\t\tresolvedOptions = { [resultsField]: options }\n\t\t\t}\n\t\t}\n\t} else {\n\t\tconst poll = pollConfigOf(form.poll)\n\t\tif (form.pollEnabled !== true || !poll) {\n\t\t\treturn forbidden\n\t\t}\n\t\tif (poll.resultsVisibility === 'afterClose' && !isPollClosed(poll)) {\n\t\t\treturn forbidden\n\t\t}\n\t\tif (access) {\n\t\t\t// No req means the seam cannot be evaluated; fail closed rather than skip a configured gate.\n\t\t\t// The concrete generated Form doc has no index signature; the seam's Record<string, unknown>\n\t\t\t// is the ergonomic host-facing contract, so widen the doc to it here.\n\t\t\tconst allowed = req\n\t\t\t\t? await access({ req, form: form as unknown as FormResultsAccessArgs['form'] })\n\t\t\t\t: false\n\t\t\tif (!allowed) {\n\t\t\t\treturn forbidden\n\t\t\t}\n\t\t}\n\t\tconst publicField =\n\t\t\ttypeof poll.resultsField === 'string' && poll.resultsField.length > 0\n\t\t\t\t? poll.resultsField\n\t\t\t\t: undefined\n\t\tif (!publicField) {\n\t\t\treturn forbidden\n\t\t}\n\t\tif (field && field !== publicField) {\n\t\t\treturn forbidden\n\t\t}\n\t\tconst instances = Array.isArray(form.fields) ? (form.fields as FormFieldInstance[]) : []\n\t\tconst instance = instances.find((entry) => entry.name === publicField)\n\t\tif (!instance) {\n\t\t\treturn forbidden\n\t\t}\n\t\tconst hasSource = typeof poll.optionSource === 'string' && poll.optionSource.length > 0\n\t\tconst authored = fieldHasOptions(instance)\n\t\t// Options that don't come from the author's own literal `options` list (a source or a\n\t\t// field-typed resolver) require the results field to be a poll-eligible type, so a legacy or\n\t\t// db-written doc pointing `resultsField` at a free-text field can never dump raw answers as\n\t\t// leftover buckets. A static authored poll is a choice field already, so it keeps serving.\n\t\tif ((hasSource || !authored) && eligibleTypes && !eligibleTypes.includes(instance.blockType)) {\n\t\t\treturn forbidden\n\t\t}\n\t\tlet options: PollOption[]\n\t\ttry {\n\t\t\toptions = await resolveEffectivePollOptions({ payload, req, form })\n\t\t} catch {\n\t\t\treturn unavailable\n\t\t}\n\t\tif (options.length === 0) {\n\t\t\treturn forbidden\n\t\t}\n\t\tresolvedOptions = { [publicField]: options }\n\t\tfields = [publicField]\n\t}\n\n\tconst results = await aggregateFormResponses({ payload, formId, fields, req, resolvedOptions })\n\treturn { status: 200, body: { results } }\n}\n"],"mappings":";;;;;;;AAiDA,MAAM,YAAyC;CAC9C,QAAQ;CACR,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,YAAY,CAAC,EAAE;AAC5C;AAKA,MAAM,cAA2C;CAChD,QAAQ;CACR,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,2BAA2B,CAAC,EAAE;AAC3D;;;;;;;;;;;;;;;;AAiBA,MAAa,4BAA4B,OACxC,SAC0C;CAC1C,MAAM,EAAE,SAAS,QAAQ,OAAO,UAAU,KAAK,QAAQ,kBAAkB;CACzE,IAAI,UAAU,MACb,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,kBAAkB,CAAC,EAAE;CAAE;CAE1E,MAAM,OAAO,MAAM,QACjB,SAAS;EAAE,YAAY;EAAY,IAAI;EAAQ,OAAO;EAAG,gBAAgB;EAAM;CAAI,CAAC,EACpF,YAAY,IAAI;CAClB,IAAI,CAAC,MACJ,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,YAAY,CAAC,EAAE;CAAE;CAOpE,IAAI,sBAAsB,IAAoB,GAC7C,MAAM,mBAAmB;EAAE;EAAS;EAAQ;CAAI,CAAC,EAAE,YAAY,KAAA,CAAS;CAGzE,IAAI;CACJ,IAAI;CACJ,IAAI,UAAU;EACb,SAAS,QAAQ,CAAC,KAAK,IAAI,KAAA;EAO3B,MAAM,OAAO,aAAa,KAAK,IAAI;EACnC,MAAM,eACL,OAAO,MAAM,iBAAiB,YAAY,KAAK,aAAa,SAAS,IAClE,KAAK,eACL,KAAA;EACJ,IAAI,KAAK,gBAAgB,QAAQ,iBAAiB,CAAC,SAAS,UAAU,eAAe;GACpF,MAAM,UAAwB,MAAM,4BAA4B;IAC/D;IACA;IACA;GACD,CAAC,EAAE,YAAY,CAAC,CAAC;GACjB,IAAI,QAAQ,SAAS,GACpB,kBAAkB,GAAG,eAAe,QAAQ;EAE9C;CACD,OAAO;EACN,MAAM,OAAO,aAAa,KAAK,IAAI;EACnC,IAAI,KAAK,gBAAgB,QAAQ,CAAC,MACjC,OAAO;EAER,IAAI,KAAK,sBAAsB,gBAAgB,CAAC,aAAa,IAAI,GAChE,OAAO;EAER,IAAI;OAOC,EAHY,MACb,MAAM,OAAO;IAAE;IAAW;GAAiD,CAAC,IAC5E,QAEF,OAAO;EAAA;EAGT,MAAM,cACL,OAAO,KAAK,iBAAiB,YAAY,KAAK,aAAa,SAAS,IACjE,KAAK,eACL,KAAA;EACJ,IAAI,CAAC,aACJ,OAAO;EAER,IAAI,SAAS,UAAU,aACtB,OAAO;EAGR,MAAM,YADY,MAAM,QAAQ,KAAK,MAAM,IAAK,KAAK,SAAiC,CAAC,GAC5D,MAAM,UAAU,MAAM,SAAS,WAAW;EACrE,IAAI,CAAC,UACJ,OAAO;EAER,MAAM,YAAY,OAAO,KAAK,iBAAiB,YAAY,KAAK,aAAa,SAAS;EACtF,MAAM,WAAW,gBAAgB,QAAQ;EAKzC,KAAK,aAAa,CAAC,aAAa,iBAAiB,CAAC,cAAc,SAAS,SAAS,SAAS,GAC1F,OAAO;EAER,IAAI;EACJ,IAAI;GACH,UAAU,MAAM,4BAA4B;IAAE;IAAS;IAAK;GAAK,CAAC;EACnE,QAAQ;GACP,OAAO;EACR;EACA,IAAI,QAAQ,WAAW,GACtB,OAAO;EAER,kBAAkB,GAAG,cAAc,QAAQ;EAC3C,SAAS,CAAC,WAAW;CACtB;CAGA,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,SAAA,MADR,uBAAuB;GAAE;GAAS;GAAQ;GAAQ;GAAK;EAAgB,CAAC,EACxD;CAAE;AACzC"}
+{"version":3,"file":"resolveResultsRequest.js","names":[],"sources":["../../src/aggregation/resolveResultsRequest.ts"],"sourcesContent":["import type { Payload, PayloadRequest } from 'payload'\nimport { FORMS_SLUG } from '../collections/forms'\nimport { isPollClosed, pollConfigOf } from '../form/pollState'\nimport { type PollFormLike, shouldAutoResolvePoll } from '../poll/closeJob'\nimport type { PollOption } from '../poll/definePollOptionSource'\nimport { resolveEffectivePollOptions } from '../poll/effectivePollOptions'\nimport { resolvePollOutcome } from '../poll/resolvePollOutcome'\nimport { aggregateFromVotes } from '../poll/votes/aggregateFromVotes'\nimport type { FormFieldInstance } from '../submissions/types'\nimport { aggregateFormResponses, fieldHasOptions } from './aggregateResponses'\nimport type { FieldAggregation } from './types'\n\nexport type FormResultsAccessArgs = {\n\treq: PayloadRequest\n\t/** The loaded forms document (depth 0). Untyped beyond `id`: hosts read their own fields (e.g. `form.tenant`). */\n\tform: { id: number | string } & Record<string, unknown>\n}\n\n/**\n * Host seam gating anonymous results reads, evaluated after the form is loaded and before anything\n * is aggregated. Multi-tenant recipe: compare `form.tenant` against the tenant derived from `req`\n * (host header, cookie, or auth context) and return `false` for a cross-tenant read. Authenticated\n * callers bypass this seam (they are admin-trusted, like the rest of the results endpoint).\n */\nexport type FormResultsAccess = (args: FormResultsAccessArgs) => boolean | Promise<boolean>\n\nexport type ResolveResultsRequestArgs = {\n\tpayload: Payload\n\tformId: number | string | undefined\n\t/** The requested field (query param). */\n\tfield?: string\n\t/** Whether the caller is authenticated (an admin/user). */\n\tisAuthed: boolean\n\treq?: PayloadRequest\n\t/** Optional host seam for anonymous reads; absent means plugin-default gating only. */\n\taccess?: FormResultsAccess\n\t/**\n\t * Poll-eligible field types (registry-derived). When set, an anonymous read of an\n\t * option-source poll also requires the results field's instance to be one of these types,\n\t * so legacy or db-written docs pointing at a free-text field can never expose stored\n\t * answers as leftover result buckets.\n\t */\n\teligibleTypes?: readonly string[]\n\t/**\n\t * Whether the hidden tally store backs poll reads. When true, the poll results field is served\n\t * from `aggregateFromVotes` (anonymous reads, and an authed read naming exactly that field)\n\t * instead of the submission scan; every authorization gate stays identical either way.\n\t */\n\tpollVotesEnabled?: boolean\n}\n\nexport type ResolveResultsRequestResult = {\n\tstatus: number\n\tbody: { results: FieldAggregation[] } | { errors: { message: string }[] }\n}\n\nconst forbidden: ResolveResultsRequestResult = {\n\tstatus: 403,\n\tbody: { errors: [{ message: 'Forbidden' }] },\n}\n\n// 503 over 403 for a failed option-source resolve: the form and its poll config are already\n// publicly readable, so \"temporarily unavailable\" leaks nothing new, matches the submission\n// path's precedent, and does not mislabel a transient server fault as an authorization denial.\nconst unavailable: ResolveResultsRequestResult = {\n\tstatus: 503,\n\tbody: { errors: [{ message: 'Poll options unavailable' }] },\n}\n\n/** Scan-shape parity for a tally-served field: label from the live instance, else the field name. */\nconst tallyMetaOf = (\n\tinstance: FormFieldInstance | undefined,\n\tfield: string\n): { label: string; fieldType?: string } => ({\n\tlabel: typeof instance?.label === 'string' && instance.label.length > 0 ? instance.label : field,\n\tfieldType: instance?.blockType,\n})\n\n/**\n * Authorize and resolve a poll/survey results request. Authed callers may aggregate any field (or all\n * enumerable fields) and bypass the `access` seam; for a poll-enabled form they also get the results\n * field's effective options injected so sourced/resolver-backed polls render labels (best-effort, a\n * resolve failure degrades to raw values rather than blocking the trusted read). Anonymous callers are\n * allowed only when the form's poll is enabled, the poll's `resultsVisibility` permits it (`afterVote`:\n * any time; `afterClose`: only once `closesAt` has passed), and the optional host `access` seam\n * approves; and then only for the configured `poll.resultsField`, and only if that field is enumerable\n * so a misconfigured `resultsField` pointing at a free-text or PII field can never be dumped publicly. A\n * static poll is enumerable through its authored options; a poll whose options come from an\n * `optionSource` or the field type's own `resolveOptions` resolves them here (registry via\n * `config.custom`, per-request cache), gated by `eligibleTypes` and enumerable only when resolution\n * yields any, with the resolved options driving bucket order and labels. Resolution failure fails\n * closed (503) on the anonymous path. Returns only aggregate counts, never raw submissions.\n */\nexport const resolveFormResultsRequest = async (\n\targs: ResolveResultsRequestArgs\n): Promise<ResolveResultsRequestResult> => {\n\tconst { payload, formId, field, isAuthed, req, access, eligibleTypes, pollVotesEnabled } = args\n\tif (formId == null) {\n\t\treturn { status: 400, body: { errors: [{ message: 'Missing form id' }] } }\n\t}\n\tconst form = await payload\n\t\t.findByID({ collection: FORMS_SLUG, id: formId, depth: 0, overrideAccess: true, req })\n\t\t.catch(() => null)\n\tif (!form) {\n\t\treturn { status: 404, body: { errors: [{ message: 'Not found' }] } }\n\t}\n\n\t// No-runner safety net: when a closed poll's `mostVoted`/`source` outcome was never auto-resolved\n\t// (no wired job runner fired the close task), a results read heals it. Idempotent and gate-neutral,\n\t// it runs on the already-loaded form via overrideAccess and writes only through the outcome hook, so\n\t// it cannot relax the anonymous authorization below. A failure degrades silently to the normal path.\n\tif (shouldAutoResolvePoll(form as PollFormLike)) {\n\t\tawait resolvePollOutcome({ payload, formId, req, pollVotesEnabled }).catch(() => undefined)\n\t}\n\n\tlet fields: string[] | undefined\n\tlet resolvedOptions: Record<string, { value: string; label: string }[]> | undefined\n\tif (isAuthed) {\n\t\tfields = field ? [field] : undefined\n\t\t// Label a poll's results field for admins: resolve its effective options (a source, the\n\t\t// field type's own resolver, or authored options) and inject them so a sourced/resolved poll\n\t\t// shows labels instead of raw stored values, and so an all-fields read still surfaces a\n\t\t// resolver-backed field that carries no authored options. Best-effort: a resolver/source\n\t\t// failure degrades to raw values rather than blocking the trusted read (the anonymous path\n\t\t// below fails closed instead). Only run when the read would actually surface the results field.\n\t\tconst poll = pollConfigOf(form.poll)\n\t\tconst resultsField =\n\t\t\ttypeof poll?.resultsField === 'string' && poll.resultsField.length > 0\n\t\t\t\t? poll.resultsField\n\t\t\t\t: undefined\n\t\tif (form.pollEnabled === true && resultsField && (!field || field === resultsField)) {\n\t\t\tconst options: PollOption[] = await resolveEffectivePollOptions({\n\t\t\t\tpayload,\n\t\t\t\treq,\n\t\t\t\tform,\n\t\t\t}).catch(() => [])\n\t\t\tif (options.length > 0) {\n\t\t\t\tresolvedOptions = { [resultsField]: options }\n\t\t\t}\n\t\t\t// Only the explicit single-field poll read switches to the tally store; an all-fields\n\t\t\t// (or multi-field) read keeps the scan, which is the only source for non-poll fields.\n\t\t\tif (pollVotesEnabled === true && field === resultsField) {\n\t\t\t\tconst instances = Array.isArray(form.fields) ? (form.fields as FormFieldInstance[]) : []\n\t\t\t\tconst instance = instances.find((entry) => entry.name === resultsField)\n\t\t\t\tconst aggregation = await aggregateFromVotes({\n\t\t\t\t\tpayload,\n\t\t\t\t\tformId,\n\t\t\t\t\tfield: resultsField,\n\t\t\t\t\tmeta: tallyMetaOf(instance, resultsField),\n\t\t\t\t\toptions: resolvedOptions?.[resultsField] ?? [],\n\t\t\t\t\treq,\n\t\t\t\t})\n\t\t\t\treturn { status: 200, body: { results: [aggregation] } }\n\t\t\t}\n\t\t}\n\t} else {\n\t\tconst poll = pollConfigOf(form.poll)\n\t\tif (form.pollEnabled !== true || !poll) {\n\t\t\treturn forbidden\n\t\t}\n\t\tif (poll.resultsVisibility === 'afterClose' && !isPollClosed(poll)) {\n\t\t\treturn forbidden\n\t\t}\n\t\tif (access) {\n\t\t\t// No req means the seam cannot be evaluated; fail closed rather than skip a configured gate.\n\t\t\t// The concrete generated Form doc has no index signature; the seam's Record<string, unknown>\n\t\t\t// is the ergonomic host-facing contract, so widen the doc to it here.\n\t\t\tconst allowed = req\n\t\t\t\t? await access({ req, form: form as unknown as FormResultsAccessArgs['form'] })\n\t\t\t\t: false\n\t\t\tif (!allowed) {\n\t\t\t\treturn forbidden\n\t\t\t}\n\t\t}\n\t\tconst publicField =\n\t\t\ttypeof poll.resultsField === 'string' && poll.resultsField.length > 0\n\t\t\t\t? poll.resultsField\n\t\t\t\t: undefined\n\t\tif (!publicField) {\n\t\t\treturn forbidden\n\t\t}\n\t\tif (field && field !== publicField) {\n\t\t\treturn forbidden\n\t\t}\n\t\tconst instances = Array.isArray(form.fields) ? (form.fields as FormFieldInstance[]) : []\n\t\tconst instance = instances.find((entry) => entry.name === publicField)\n\t\tif (!instance) {\n\t\t\treturn forbidden\n\t\t}\n\t\tconst hasSource = typeof poll.optionSource === 'string' && poll.optionSource.length > 0\n\t\tconst authored = fieldHasOptions(instance)\n\t\t// Options that don't come from the author's own literal `options` list (a source or a\n\t\t// field-typed resolver) require the results field to be a poll-eligible type, so a legacy or\n\t\t// db-written doc pointing `resultsField` at a free-text field can never dump raw answers as\n\t\t// leftover buckets. A static authored poll is a choice field already, so it keeps serving.\n\t\tif ((hasSource || !authored) && eligibleTypes && !eligibleTypes.includes(instance.blockType)) {\n\t\t\treturn forbidden\n\t\t}\n\t\tlet options: PollOption[]\n\t\ttry {\n\t\t\toptions = await resolveEffectivePollOptions({ payload, req, form })\n\t\t} catch {\n\t\t\treturn unavailable\n\t\t}\n\t\tif (options.length === 0) {\n\t\t\treturn forbidden\n\t\t}\n\t\tif (pollVotesEnabled === true) {\n\t\t\tconst aggregation = await aggregateFromVotes({\n\t\t\t\tpayload,\n\t\t\t\tformId,\n\t\t\t\tfield: publicField,\n\t\t\t\tmeta: tallyMetaOf(instance, publicField),\n\t\t\t\toptions,\n\t\t\t\treq,\n\t\t\t})\n\t\t\treturn { status: 200, body: { results: [aggregation] } }\n\t\t}\n\t\tresolvedOptions = { [publicField]: options }\n\t\tfields = [publicField]\n\t}\n\n\tconst results = await aggregateFormResponses({ payload, formId, fields, req, resolvedOptions })\n\treturn { status: 200, body: { results } }\n}\n"],"mappings":";;;;;;;;AAwDA,MAAM,YAAyC;CAC9C,QAAQ;CACR,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,YAAY,CAAC,EAAE;AAC5C;AAKA,MAAM,cAA2C;CAChD,QAAQ;CACR,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,2BAA2B,CAAC,EAAE;AAC3D;;AAGA,MAAM,eACL,UACA,WAC4C;CAC5C,OAAO,OAAO,UAAU,UAAU,YAAY,SAAS,MAAM,SAAS,IAAI,SAAS,QAAQ;CAC3F,WAAW,UAAU;AACtB;;;;;;;;;;;;;;;;AAiBA,MAAa,4BAA4B,OACxC,SAC0C;CAC1C,MAAM,EAAE,SAAS,QAAQ,OAAO,UAAU,KAAK,QAAQ,eAAe,qBAAqB;CAC3F,IAAI,UAAU,MACb,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,kBAAkB,CAAC,EAAE;CAAE;CAE1E,MAAM,OAAO,MAAM,QACjB,SAAS;EAAE,YAAY;EAAY,IAAI;EAAQ,OAAO;EAAG,gBAAgB;EAAM;CAAI,CAAC,EACpF,YAAY,IAAI;CAClB,IAAI,CAAC,MACJ,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,YAAY,CAAC,EAAE;CAAE;CAOpE,IAAI,sBAAsB,IAAoB,GAC7C,MAAM,mBAAmB;EAAE;EAAS;EAAQ;EAAK;CAAiB,CAAC,EAAE,YAAY,KAAA,CAAS;CAG3F,IAAI;CACJ,IAAI;CACJ,IAAI,UAAU;EACb,SAAS,QAAQ,CAAC,KAAK,IAAI,KAAA;EAO3B,MAAM,OAAO,aAAa,KAAK,IAAI;EACnC,MAAM,eACL,OAAO,MAAM,iBAAiB,YAAY,KAAK,aAAa,SAAS,IAClE,KAAK,eACL,KAAA;EACJ,IAAI,KAAK,gBAAgB,QAAQ,iBAAiB,CAAC,SAAS,UAAU,eAAe;GACpF,MAAM,UAAwB,MAAM,4BAA4B;IAC/D;IACA;IACA;GACD,CAAC,EAAE,YAAY,CAAC,CAAC;GACjB,IAAI,QAAQ,SAAS,GACpB,kBAAkB,GAAG,eAAe,QAAQ;GAI7C,IAAI,qBAAqB,QAAQ,UAAU,cAW1C,OAAO;IAAE,QAAQ;IAAK,MAAM,EAAE,SAAS,CAAC,MARd,mBAAmB;KAC5C;KACA;KACA,OAAO;KACP,MAAM,aANW,MAAM,QAAQ,KAAK,MAAM,IAAK,KAAK,SAAiC,CAAC,GAC5D,MAAM,UAAU,MAAM,SAAS,YAKhC,GAAG,YAAY;KACxC,SAAS,kBAAkB,iBAAiB,CAAC;KAC7C;IACD,CAAC,CACkD,EAAE;GAAE;EAEzD;CACD,OAAO;EACN,MAAM,OAAO,aAAa,KAAK,IAAI;EACnC,IAAI,KAAK,gBAAgB,QAAQ,CAAC,MACjC,OAAO;EAER,IAAI,KAAK,sBAAsB,gBAAgB,CAAC,aAAa,IAAI,GAChE,OAAO;EAER,IAAI;OAOC,EAHY,MACb,MAAM,OAAO;IAAE;IAAW;GAAiD,CAAC,IAC5E,QAEF,OAAO;EAAA;EAGT,MAAM,cACL,OAAO,KAAK,iBAAiB,YAAY,KAAK,aAAa,SAAS,IACjE,KAAK,eACL,KAAA;EACJ,IAAI,CAAC,aACJ,OAAO;EAER,IAAI,SAAS,UAAU,aACtB,OAAO;EAGR,MAAM,YADY,MAAM,QAAQ,KAAK,MAAM,IAAK,KAAK,SAAiC,CAAC,GAC5D,MAAM,UAAU,MAAM,SAAS,WAAW;EACrE,IAAI,CAAC,UACJ,OAAO;EAER,MAAM,YAAY,OAAO,KAAK,iBAAiB,YAAY,KAAK,aAAa,SAAS;EACtF,MAAM,WAAW,gBAAgB,QAAQ;EAKzC,KAAK,aAAa,CAAC,aAAa,iBAAiB,CAAC,cAAc,SAAS,SAAS,SAAS,GAC1F,OAAO;EAER,IAAI;EACJ,IAAI;GACH,UAAU,MAAM,4BAA4B;IAAE;IAAS;IAAK;GAAK,CAAC;EACnE,QAAQ;GACP,OAAO;EACR;EACA,IAAI,QAAQ,WAAW,GACtB,OAAO;EAER,IAAI,qBAAqB,MASxB,OAAO;GAAE,QAAQ;GAAK,MAAM,EAAE,SAAS,CAAC,MARd,mBAAmB;IAC5C;IACA;IACA,OAAO;IACP,MAAM,YAAY,UAAU,WAAW;IACvC;IACA;GACD,CAAC,CACkD,EAAE;EAAE;EAExD,kBAAkB,GAAG,cAAc,QAAQ;EAC3C,SAAS,CAAC,WAAW;CACtB;CAGA,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,SAAA,MADR,uBAAuB;GAAE;GAAS;GAAQ;GAAQ;GAAK;EAAgB,CAAC,EACxD;CAAE;AACzC"}

package/dist/calc/computeCalcFields.d.ts

@@ -1,5 +1,6 @@
-import { FormFieldInstance } from "../submissions/types.js";
 import { CalcExpression } from "./types.js";
+import { FormFieldInstance } from "../submissions/types.js";
+import { CalcResolved } from "./evaluate.js";
 
 //#region src/calc/computeCalcFields.d.ts
 /** Returns the calc expression if the field carries one (non-null object), otherwise undefined. */
@@ -7,9 +8,10 @@ declare const calcExpressionOf: (field: FormFieldInstance) => CalcExpression | u
 /**
  * Returns answers with every calc field's value derived from its expression,
  * folded in declaration order so a calc may reference an earlier calc's result.
- * Identity when no field carries an expression.
+ * Identity when no field carries an expression. `resolved` threads server-resolved
+ * source values, weight maps, and custom functions into each evaluation.
  */
-declare const computeCalcFields: (fields: FormFieldInstance[], answers: Record<string, unknown>) => Record<string, unknown>;
+declare const computeCalcFields: (fields: FormFieldInstance[], answers: Record<string, unknown>, resolved?: CalcResolved) => Record<string, unknown>;
 //#endregion
 export { calcExpressionOf, computeCalcFields };
 //# sourceMappingURL=computeCalcFields.d.ts.map

package/dist/calc/computeCalcFields.js

@@ -9,15 +9,16 @@ const calcExpressionOf = (field) => {
 /**
 * Returns answers with every calc field's value derived from its expression,
 * folded in declaration order so a calc may reference an earlier calc's result.
-* Identity when no field carries an expression.
+* Identity when no field carries an expression. `resolved` threads server-resolved
+* source values, weight maps, and custom functions into each evaluation.
 */
-const computeCalcFields = (fields, answers) => {
+const computeCalcFields = (fields, answers, resolved) => {
 	let next = answers;
 	for (const field of fields) {
 		const expr = calcExpressionOf(field);
 		if (expr && isNamedField(field)) next = {
 			...next,
-			[field.name]: evaluateCalc(expr, next)
+			[field.name]: evaluateCalc(expr, next, resolved)
 		};
 	}
 	return next;

package/dist/calc/computeCalcFields.js.map

@@ -1 +1 @@
-{"version":3,"file":"computeCalcFields.js","names":[],"sources":["../../src/calc/computeCalcFields.ts"],"sourcesContent":["import { isNamedField } from '../fields/fieldKey'\nimport type { FormFieldInstance } from '../submissions/types'\nimport { evaluateCalc } from './evaluate'\nimport type { CalcExpression } from './types'\n\n/** Returns the calc expression if the field carries one (non-null object), otherwise undefined. */\nexport const calcExpressionOf = (field: FormFieldInstance): CalcExpression | undefined => {\n\tconst expr = field.expression\n\treturn expr !== null && typeof expr === 'object' && !Array.isArray(expr)\n\t\t? (expr as CalcExpression)\n\t\t: undefined\n}\n\n/**\n * Returns answers with every calc field's value derived from its expression,\n * folded in declaration order so a calc may reference an earlier calc's result.\n * Identity when no field carries an expression.\n */\nexport const computeCalcFields = (\n\tfields: FormFieldInstance[],\n\tanswers: Record<string, unknown>\n): Record<string, unknown> => {\n\tlet next = answers\n\tfor (const field of fields) {\n\t\tconst expr = calcExpressionOf(field)\n\t\tif (expr && isNamedField(field)) {\n\t\t\tnext = { ...next, [field.name]: evaluateCalc(expr, next) }\n\t\t}\n\t}\n\treturn next\n}\n"],"mappings":";;;;AAMA,MAAa,oBAAoB,UAAyD;CACzF,MAAM,OAAO,MAAM;CACnB,OAAO,SAAS,QAAQ,OAAO,SAAS,YAAY,CAAC,MAAM,QAAQ,IAAI,IACnE,OACD,KAAA;AACJ;;;;;;AAOA,MAAa,qBACZ,QACA,YAC6B;CAC7B,IAAI,OAAO;CACX,KAAK,MAAM,SAAS,QAAQ;EAC3B,MAAM,OAAO,iBAAiB,KAAK;EACnC,IAAI,QAAQ,aAAa,KAAK,GAC7B,OAAO;GAAE,GAAG;IAAO,MAAM,OAAO,aAAa,MAAM,IAAI;EAAE;CAE3D;CACA,OAAO;AACR"}
+{"version":3,"file":"computeCalcFields.js","names":[],"sources":["../../src/calc/computeCalcFields.ts"],"sourcesContent":["import { isNamedField } from '../fields/fieldKey'\nimport type { FormFieldInstance } from '../submissions/types'\nimport { type CalcResolved, evaluateCalc } from './evaluate'\nimport type { CalcExpression } from './types'\n\n/** Returns the calc expression if the field carries one (non-null object), otherwise undefined. */\nexport const calcExpressionOf = (field: FormFieldInstance): CalcExpression | undefined => {\n\tconst expr = field.expression\n\treturn expr !== null && typeof expr === 'object' && !Array.isArray(expr)\n\t\t? (expr as CalcExpression)\n\t\t: undefined\n}\n\n/**\n * Returns answers with every calc field's value derived from its expression,\n * folded in declaration order so a calc may reference an earlier calc's result.\n * Identity when no field carries an expression. `resolved` threads server-resolved\n * source values, weight maps, and custom functions into each evaluation.\n */\nexport const computeCalcFields = (\n\tfields: FormFieldInstance[],\n\tanswers: Record<string, unknown>,\n\tresolved?: CalcResolved\n): Record<string, unknown> => {\n\tlet next = answers\n\tfor (const field of fields) {\n\t\tconst expr = calcExpressionOf(field)\n\t\tif (expr && isNamedField(field)) {\n\t\t\tnext = { ...next, [field.name]: evaluateCalc(expr, next, resolved) }\n\t\t}\n\t}\n\treturn next\n}\n"],"mappings":";;;;AAMA,MAAa,oBAAoB,UAAyD;CACzF,MAAM,OAAO,MAAM;CACnB,OAAO,SAAS,QAAQ,OAAO,SAAS,YAAY,CAAC,MAAM,QAAQ,IAAI,IACnE,OACD,KAAA;AACJ;;;;;;;AAQA,MAAa,qBACZ,QACA,SACA,aAC6B;CAC7B,IAAI,OAAO;CACX,KAAK,MAAM,SAAS,QAAQ;EAC3B,MAAM,OAAO,iBAAiB,KAAK;EACnC,IAAI,QAAQ,aAAa,KAAK,GAC7B,OAAO;GAAE,GAAG;IAAO,MAAM,OAAO,aAAa,MAAM,MAAM,QAAQ;EAAE;CAErE;CACA,OAAO;AACR"}

package/dist/calc/evaluate.d.ts

@@ -1,8 +1,31 @@
 import { CalcExpression } from "./types.js";
 
 //#region src/calc/evaluate.d.ts
-/** Evaluate a calc expression against form answers. Total + safe: no `eval`, always finite, div/mod by zero -> 0, missing ref -> 0, depth-guarded. Isomorphic (client + server). */
-declare const evaluateCalc: (expr: CalcExpression | null | undefined, answers: Record<string, unknown>) => number;
+/**
+ * Server-resolved calc extension values, threaded into evaluation as data (never re-resolved
+ * here, so the evaluator stays sync and isomorphic). `sources`/`weights` are serializable and
+ * ride the form document for the client's live preview; `functions` never serialize and are
+ * supplied per environment (registry `apply` fns on the server, the Form prop on the client).
+ */
+type CalcResolved = {
+  sources?: Record<string, number>; /** Keyed `source + ' ' + field` (see `calcWeightKey` / `resolveCalcContext`). */
+  weights?: Record<string, Record<string, number>>;
+  functions?: Record<string, (args: number[]) => number>;
+};
+/**
+ * The `CalcResolved.weights` key for a sourced weight node: source key + space + field name.
+ * Unambiguous because registered source keys can never contain a space
+ * (`assertValidCalcSourceKeys` enforces `[\w.-]` at boot), so the first space always ends the
+ * source segment.
+ */
+declare const calcWeightKey: (source: string, field: string) => string;
+/**
+ * Evaluate a calc expression against form answers. Total + safe: no `eval`, always finite, div/mod
+ * by zero -> 0, missing ref -> 0, depth-guarded. Isomorphic (client + server). `resolved` supplies
+ * server-resolved source values, sourced weight maps, and custom functions; any extension node
+ * whose value is absent evaluates to 0.
+ */
+declare const evaluateCalc: (expr: CalcExpression | null | undefined, answers: Record<string, unknown>, resolved?: CalcResolved) => number;
 //#endregion
-export { evaluateCalc };
+export { CalcResolved, calcWeightKey, evaluateCalc };
 //# sourceMappingURL=evaluate.d.ts.map

package/dist/calc/evaluate.js

@@ -1,4 +1,11 @@
 //#region src/calc/evaluate.ts
+/**
+* The `CalcResolved.weights` key for a sourced weight node: source key + space + field name.
+* Unambiguous because registered source keys can never contain a space
+* (`assertValidCalcSourceKeys` enforces `[\w.-]` at boot), so the first space always ends the
+* source segment.
+*/
+const calcWeightKey = (source, field) => `${source} ${field}`;
 const toNumber = (value) => {
 	if (typeof value === "number") return Number.isFinite(value) ? value : 0;
 	if (typeof value === "string" && value.trim() !== "") {
@@ -16,15 +23,17 @@ const FUNCTIONS = {
 	ceil: (a) => Math.ceil(a[0] ?? 0),
 	floor: (a) => Math.floor(a[0] ?? 0)
 };
-const evalNode = (expr, answers, depth) => {
+const evalNode = (expr, ctx, depth) => {
 	if (depth > 64 || expr == null || typeof expr !== "object") return 0;
+	const { answers, resolved } = ctx;
 	switch (expr.type) {
 		case "lit": return finite(toNumber(expr.value));
 		case "ref": return toNumber(answers[expr.field]);
-		case "neg": return finite(-evalNode(expr.operand, answers, depth + 1));
+		case "source": return toNumber(resolved?.sources?.[expr.source]);
+		case "neg": return finite(-evalNode(expr.operand, ctx, depth + 1));
 		case "op": {
-			const l = evalNode(expr.left, answers, depth + 1);
-			const r = evalNode(expr.right, answers, depth + 1);
+			const l = evalNode(expr.left, ctx, depth + 1);
+			const r = evalNode(expr.right, ctx, depth + 1);
 			switch (expr.op) {
 				case "+": return finite(l + r);
 				case "-": return finite(l - r);
@@ -35,24 +44,37 @@ const evalNode = (expr, answers, depth) => {
 			}
 		}
 		case "fn": {
-			const fn = FUNCTIONS[expr.fn];
+			const fn = FUNCTIONS[expr.fn] ?? resolved?.functions?.[expr.fn];
 			if (!fn) return 0;
-			return finite(fn(Array.isArray(expr.args) ? expr.args.map((a) => evalNode(a, answers, depth + 1)) : []));
+			const args = Array.isArray(expr.args) ? expr.args.map((a) => evalNode(a, ctx, depth + 1)) : [];
+			try {
+				return finite(fn(args));
+			} catch {
+				return 0;
+			}
 		}
 		case "weight": {
-			const weights = expr.weights ?? {};
+			const weights = typeof expr.source === "string" ? resolved?.weights?.[calcWeightKey(expr.source, expr.field)] ?? {} : expr.weights ?? {};
 			const value = answers[expr.field];
 			return finite((Array.isArray(value) ? value : value == null || value === "" ? [] : [value]).reduce((sum, v) => sum + toNumber(weights[String(v)]), 0));
 		}
 		default: return 0;
 	}
 };
-/** Evaluate a calc expression against form answers. Total + safe: no `eval`, always finite, div/mod by zero -> 0, missing ref -> 0, depth-guarded. Isomorphic (client + server). */
-const evaluateCalc = (expr, answers) => {
+/**
+* Evaluate a calc expression against form answers. Total + safe: no `eval`, always finite, div/mod
+* by zero -> 0, missing ref -> 0, depth-guarded. Isomorphic (client + server). `resolved` supplies
+* server-resolved source values, sourced weight maps, and custom functions; any extension node
+* whose value is absent evaluates to 0.
+*/
+const evaluateCalc = (expr, answers, resolved) => {
 	if (!expr) return 0;
-	return evalNode(expr, answers, 0);
+	return evalNode(expr, {
+		answers,
+		resolved
+	}, 0);
 };
 //#endregion
-export { evaluateCalc };
+export { calcWeightKey, evaluateCalc };
 
 //# sourceMappingURL=evaluate.js.map

package/dist/calc/evaluate.js.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate.js","names":[],"sources":["../../src/calc/evaluate.ts"],"sourcesContent":["import { type CalcExpression, MAX_DEPTH } from './types'\n\nconst toNumber = (value: unknown): number => {\n\tif (typeof value === 'number') {\n\t\treturn Number.isFinite(value) ? value : 0\n\t}\n\tif (typeof value === 'string' && value.trim() !== '') {\n\t\tconst n = Number(value)\n\t\treturn Number.isFinite(n) ? n : 0\n\t}\n\treturn 0\n}\n\nconst finite = (n: number): number => (Number.isFinite(n) ? n : 0)\n\nconst FUNCTIONS: Record<string, (args: number[]) => number> = {\n\tmin: (a) => (a.length ? Math.min(...a) : 0),\n\tmax: (a) => (a.length ? Math.max(...a) : 0),\n\tround: (a) => Math.round(a[0] ?? 0),\n\tabs: (a) => Math.abs(a[0] ?? 0),\n\tceil: (a) => Math.ceil(a[0] ?? 0),\n\tfloor: (a) => Math.floor(a[0] ?? 0),\n}\n\nconst evalNode = (\n\texpr: CalcExpression,\n\tanswers: Record<string, unknown>,\n\tdepth: number\n): number => {\n\tif (depth > MAX_DEPTH || expr == null || typeof expr !== 'object') {\n\t\treturn 0\n\t}\n\tswitch (expr.type) {\n\t\tcase 'lit':\n\t\t\treturn finite(toNumber(expr.value))\n\t\tcase 'ref':\n\t\t\treturn toNumber(answers[expr.field])\n\t\tcase 'neg':\n\t\t\treturn finite(-evalNode(expr.operand, answers, depth + 1))\n\t\tcase 'op': {\n\t\t\tconst l = evalNode(expr.left, answers, depth + 1)\n\t\t\tconst r = evalNode(expr.right, answers, depth + 1)\n\t\t\tswitch (expr.op) {\n\t\t\t\tcase '+':\n\t\t\t\t\treturn finite(l + r)\n\t\t\t\tcase '-':\n\t\t\t\t\treturn finite(l - r)\n\t\t\t\tcase '*':\n\t\t\t\t\treturn finite(l * r)\n\t\t\t\tcase '/':\n\t\t\t\t\treturn r === 0 ? 0 : finite(l / r)\n\t\t\t\tcase '%':\n\t\t\t\t\treturn r === 0 ? 0 : finite(l % r)\n\t\t\t\tdefault:\n\t\t\t\t\treturn 0\n\t\t\t}\n\t\t}\n\t\tcase 'fn': {\n\t\t\tconst fn = FUNCTIONS[expr.fn]\n\t\t\tif (!fn) {\n\t\t\t\treturn 0\n\t\t\t}\n\t\t\tconst args = Array.isArray(expr.args)\n\t\t\t\t? expr.args.map((a) => evalNode(a, answers, depth + 1))\n\t\t\t\t: []\n\t\t\treturn finite(fn(args))\n\t\t}\n\t\tcase 'weight': {\n\t\t\tconst weights = expr.weights ?? {}\n\t\t\tconst value = answers[expr.field]\n\t\t\tconst chosen = Array.isArray(value) ? value : value == null || value === '' ? [] : [value]\n\t\t\treturn finite(\n\t\t\t\tchosen.reduce((sum: number, v: unknown) => sum + toNumber(weights[String(v)]), 0)\n\t\t\t)\n\t\t}\n\t\tdefault:\n\t\t\treturn 0\n\t}\n}\n\n/** Evaluate a calc expression against form answers. Total + safe: no `eval`, always finite, div/mod by zero -> 0, missing ref -> 0, depth-guarded. Isomorphic (client + server). */\nexport const evaluateCalc = (\n\texpr: CalcExpression | null | undefined,\n\tanswers: Record<string, unknown>\n): number => {\n\tif (!expr) {\n\t\treturn 0\n\t}\n\treturn evalNode(expr, answers, 0)\n}\n"],"mappings":";AAEA,MAAM,YAAY,UAA2B;CAC5C,IAAI,OAAO,UAAU,UACpB,OAAO,OAAO,SAAS,KAAK,IAAI,QAAQ;CAEzC,IAAI,OAAO,UAAU,YAAY,MAAM,KAAK,MAAM,IAAI;EACrD,MAAM,IAAI,OAAO,KAAK;EACtB,OAAO,OAAO,SAAS,CAAC,IAAI,IAAI;CACjC;CACA,OAAO;AACR;AAEA,MAAM,UAAU,MAAuB,OAAO,SAAS,CAAC,IAAI,IAAI;AAEhE,MAAM,YAAwD;CAC7D,MAAM,MAAO,EAAE,SAAS,KAAK,IAAI,GAAG,CAAC,IAAI;CACzC,MAAM,MAAO,EAAE,SAAS,KAAK,IAAI,GAAG,CAAC,IAAI;CACzC,QAAQ,MAAM,KAAK,MAAM,EAAE,MAAM,CAAC;CAClC,MAAM,MAAM,KAAK,IAAI,EAAE,MAAM,CAAC;CAC9B,OAAO,MAAM,KAAK,KAAK,EAAE,MAAM,CAAC;CAChC,QAAQ,MAAM,KAAK,MAAM,EAAE,MAAM,CAAC;AACnC;AAEA,MAAM,YACL,MACA,SACA,UACY;CACZ,IAAI,QAAA,MAAqB,QAAQ,QAAQ,OAAO,SAAS,UACxD,OAAO;CAER,QAAQ,KAAK,MAAb;EACC,KAAK,OACJ,OAAO,OAAO,SAAS,KAAK,KAAK,CAAC;EACnC,KAAK,OACJ,OAAO,SAAS,QAAQ,KAAK,MAAM;EACpC,KAAK,OACJ,OAAO,OAAO,CAAC,SAAS,KAAK,SAAS,SAAS,QAAQ,CAAC,CAAC;EAC1D,KAAK,MAAM;GACV,MAAM,IAAI,SAAS,KAAK,MAAM,SAAS,QAAQ,CAAC;GAChD,MAAM,IAAI,SAAS,KAAK,OAAO,SAAS,QAAQ,CAAC;GACjD,QAAQ,KAAK,IAAb;IACC,KAAK,KACJ,OAAO,OAAO,IAAI,CAAC;IACpB,KAAK,KACJ,OAAO,OAAO,IAAI,CAAC;IACpB,KAAK,KACJ,OAAO,OAAO,IAAI,CAAC;IACpB,KAAK,KACJ,OAAO,MAAM,IAAI,IAAI,OAAO,IAAI,CAAC;IAClC,KAAK,KACJ,OAAO,MAAM,IAAI,IAAI,OAAO,IAAI,CAAC;IAClC,SACC,OAAO;GACT;EACD;EACA,KAAK,MAAM;GACV,MAAM,KAAK,UAAU,KAAK;GAC1B,IAAI,CAAC,IACJ,OAAO;GAKR,OAAO,OAAO,GAHD,MAAM,QAAQ,KAAK,IAAI,IACjC,KAAK,KAAK,KAAK,MAAM,SAAS,GAAG,SAAS,QAAQ,CAAC,CAAC,IACpD,CAAC,CACiB,CAAC;EACvB;EACA,KAAK,UAAU;GACd,MAAM,UAAU,KAAK,WAAW,CAAC;GACjC,MAAM,QAAQ,QAAQ,KAAK;GAE3B,OAAO,QADQ,MAAM,QAAQ,KAAK,IAAI,QAAQ,SAAS,QAAQ,UAAU,KAAK,CAAC,IAAI,CAAC,KAAK,GAEjF,QAAQ,KAAa,MAAe,MAAM,SAAS,QAAQ,OAAO,CAAC,EAAE,GAAG,CAAC,CACjF;EACD;EACA,SACC,OAAO;CACT;AACD;;AAGA,MAAa,gBACZ,MACA,YACY;CACZ,IAAI,CAAC,MACJ,OAAO;CAER,OAAO,SAAS,MAAM,SAAS,CAAC;AACjC"}
+{"version":3,"file":"evaluate.js","names":[],"sources":["../../src/calc/evaluate.ts"],"sourcesContent":["import { type CalcExpression, MAX_DEPTH } from './types'\n\n/**\n * Server-resolved calc extension values, threaded into evaluation as data (never re-resolved\n * here, so the evaluator stays sync and isomorphic). `sources`/`weights` are serializable and\n * ride the form document for the client's live preview; `functions` never serialize and are\n * supplied per environment (registry `apply` fns on the server, the Form prop on the client).\n */\nexport type CalcResolved = {\n\tsources?: Record<string, number>\n\t/** Keyed `source + ' ' + field` (see `calcWeightKey` / `resolveCalcContext`). */\n\tweights?: Record<string, Record<string, number>>\n\tfunctions?: Record<string, (args: number[]) => number>\n}\n\n/**\n * The `CalcResolved.weights` key for a sourced weight node: source key + space + field name.\n * Unambiguous because registered source keys can never contain a space\n * (`assertValidCalcSourceKeys` enforces `[\\w.-]` at boot), so the first space always ends the\n * source segment.\n */\nexport const calcWeightKey = (source: string, field: string): string => `${source} ${field}`\n\nconst toNumber = (value: unknown): number => {\n\tif (typeof value === 'number') {\n\t\treturn Number.isFinite(value) ? value : 0\n\t}\n\tif (typeof value === 'string' && value.trim() !== '') {\n\t\tconst n = Number(value)\n\t\treturn Number.isFinite(n) ? n : 0\n\t}\n\treturn 0\n}\n\nconst finite = (n: number): number => (Number.isFinite(n) ? n : 0)\n\nconst FUNCTIONS: Record<string, (args: number[]) => number> = {\n\tmin: (a) => (a.length ? Math.min(...a) : 0),\n\tmax: (a) => (a.length ? Math.max(...a) : 0),\n\tround: (a) => Math.round(a[0] ?? 0),\n\tabs: (a) => Math.abs(a[0] ?? 0),\n\tceil: (a) => Math.ceil(a[0] ?? 0),\n\tfloor: (a) => Math.floor(a[0] ?? 0),\n}\n\ntype EvalContext = { answers: Record<string, unknown>; resolved?: CalcResolved }\n\nconst evalNode = (expr: CalcExpression, ctx: EvalContext, depth: number): number => {\n\tif (depth > MAX_DEPTH || expr == null || typeof expr !== 'object') {\n\t\treturn 0\n\t}\n\tconst { answers, resolved } = ctx\n\tswitch (expr.type) {\n\t\tcase 'lit':\n\t\t\treturn finite(toNumber(expr.value))\n\t\tcase 'ref':\n\t\t\treturn toNumber(answers[expr.field])\n\t\tcase 'source':\n\t\t\treturn toNumber(resolved?.sources?.[expr.source])\n\t\tcase 'neg':\n\t\t\treturn finite(-evalNode(expr.operand, ctx, depth + 1))\n\t\tcase 'op': {\n\t\t\tconst l = evalNode(expr.left, ctx, depth + 1)\n\t\t\tconst r = evalNode(expr.right, ctx, depth + 1)\n\t\t\tswitch (expr.op) {\n\t\t\t\tcase '+':\n\t\t\t\t\treturn finite(l + r)\n\t\t\t\tcase '-':\n\t\t\t\t\treturn finite(l - r)\n\t\t\t\tcase '*':\n\t\t\t\t\treturn finite(l * r)\n\t\t\t\tcase '/':\n\t\t\t\t\treturn r === 0 ? 0 : finite(l / r)\n\t\t\t\tcase '%':\n\t\t\t\t\treturn r === 0 ? 0 : finite(l % r)\n\t\t\t\tdefault:\n\t\t\t\t\treturn 0\n\t\t\t}\n\t\t}\n\t\tcase 'fn': {\n\t\t\t// Built-ins always win, so a resolved custom fn can never shadow the canonical grammar.\n\t\t\tconst fn = FUNCTIONS[expr.fn] ?? resolved?.functions?.[expr.fn]\n\t\t\tif (!fn) {\n\t\t\t\treturn 0\n\t\t\t}\n\t\t\tconst args = Array.isArray(expr.args) ? expr.args.map((a) => evalNode(a, ctx, depth + 1)) : []\n\t\t\t// Custom fns are host code: a throw must degrade to 0, not break the whole evaluation.\n\t\t\ttry {\n\t\t\t\treturn finite(fn(args))\n\t\t\t} catch {\n\t\t\t\treturn 0\n\t\t\t}\n\t\t}\n\t\tcase 'weight': {\n\t\t\t// A sourced weight always reads the resolved map (missing map -> 0 per chosen); inline weights are ignored.\n\t\t\tconst weights =\n\t\t\t\ttypeof expr.source === 'string'\n\t\t\t\t\t? (resolved?.weights?.[calcWeightKey(expr.source, expr.field)] ?? {})\n\t\t\t\t\t: (expr.weights ?? {})\n\t\t\tconst value = answers[expr.field]\n\t\t\tconst chosen = Array.isArray(value) ? value : value == null || value === '' ? [] : [value]\n\t\t\treturn finite(\n\t\t\t\tchosen.reduce((sum: number, v: unknown) => sum + toNumber(weights[String(v)]), 0)\n\t\t\t)\n\t\t}\n\t\tdefault:\n\t\t\treturn 0\n\t}\n}\n\n/**\n * Evaluate a calc expression against form answers. Total + safe: no `eval`, always finite, div/mod\n * by zero -> 0, missing ref -> 0, depth-guarded. Isomorphic (client + server). `resolved` supplies\n * server-resolved source values, sourced weight maps, and custom functions; any extension node\n * whose value is absent evaluates to 0.\n */\nexport const evaluateCalc = (\n\texpr: CalcExpression | null | undefined,\n\tanswers: Record<string, unknown>,\n\tresolved?: CalcResolved\n): number => {\n\tif (!expr) {\n\t\treturn 0\n\t}\n\treturn evalNode(expr, { answers, resolved }, 0)\n}\n"],"mappings":";;;;;;;AAqBA,MAAa,iBAAiB,QAAgB,UAA0B,GAAG,OAAO,GAAG;AAErF,MAAM,YAAY,UAA2B;CAC5C,IAAI,OAAO,UAAU,UACpB,OAAO,OAAO,SAAS,KAAK,IAAI,QAAQ;CAEzC,IAAI,OAAO,UAAU,YAAY,MAAM,KAAK,MAAM,IAAI;EACrD,MAAM,IAAI,OAAO,KAAK;EACtB,OAAO,OAAO,SAAS,CAAC,IAAI,IAAI;CACjC;CACA,OAAO;AACR;AAEA,MAAM,UAAU,MAAuB,OAAO,SAAS,CAAC,IAAI,IAAI;AAEhE,MAAM,YAAwD;CAC7D,MAAM,MAAO,EAAE,SAAS,KAAK,IAAI,GAAG,CAAC,IAAI;CACzC,MAAM,MAAO,EAAE,SAAS,KAAK,IAAI,GAAG,CAAC,IAAI;CACzC,QAAQ,MAAM,KAAK,MAAM,EAAE,MAAM,CAAC;CAClC,MAAM,MAAM,KAAK,IAAI,EAAE,MAAM,CAAC;CAC9B,OAAO,MAAM,KAAK,KAAK,EAAE,MAAM,CAAC;CAChC,QAAQ,MAAM,KAAK,MAAM,EAAE,MAAM,CAAC;AACnC;AAIA,MAAM,YAAY,MAAsB,KAAkB,UAA0B;CACnF,IAAI,QAAA,MAAqB,QAAQ,QAAQ,OAAO,SAAS,UACxD,OAAO;CAER,MAAM,EAAE,SAAS,aAAa;CAC9B,QAAQ,KAAK,MAAb;EACC,KAAK,OACJ,OAAO,OAAO,SAAS,KAAK,KAAK,CAAC;EACnC,KAAK,OACJ,OAAO,SAAS,QAAQ,KAAK,MAAM;EACpC,KAAK,UACJ,OAAO,SAAS,UAAU,UAAU,KAAK,OAAO;EACjD,KAAK,OACJ,OAAO,OAAO,CAAC,SAAS,KAAK,SAAS,KAAK,QAAQ,CAAC,CAAC;EACtD,KAAK,MAAM;GACV,MAAM,IAAI,SAAS,KAAK,MAAM,KAAK,QAAQ,CAAC;GAC5C,MAAM,IAAI,SAAS,KAAK,OAAO,KAAK,QAAQ,CAAC;GAC7C,QAAQ,KAAK,IAAb;IACC,KAAK,KACJ,OAAO,OAAO,IAAI,CAAC;IACpB,KAAK,KACJ,OAAO,OAAO,IAAI,CAAC;IACpB,KAAK,KACJ,OAAO,OAAO,IAAI,CAAC;IACpB,KAAK,KACJ,OAAO,MAAM,IAAI,IAAI,OAAO,IAAI,CAAC;IAClC,KAAK,KACJ,OAAO,MAAM,IAAI,IAAI,OAAO,IAAI,CAAC;IAClC,SACC,OAAO;GACT;EACD;EACA,KAAK,MAAM;GAEV,MAAM,KAAK,UAAU,KAAK,OAAO,UAAU,YAAY,KAAK;GAC5D,IAAI,CAAC,IACJ,OAAO;GAER,MAAM,OAAO,MAAM,QAAQ,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,MAAM,SAAS,GAAG,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC;GAE7F,IAAI;IACH,OAAO,OAAO,GAAG,IAAI,CAAC;GACvB,QAAQ;IACP,OAAO;GACR;EACD;EACA,KAAK,UAAU;GAEd,MAAM,UACL,OAAO,KAAK,WAAW,WACnB,UAAU,UAAU,cAAc,KAAK,QAAQ,KAAK,KAAK,MAAM,CAAC,IAChE,KAAK,WAAW,CAAC;GACtB,MAAM,QAAQ,QAAQ,KAAK;GAE3B,OAAO,QADQ,MAAM,QAAQ,KAAK,IAAI,QAAQ,SAAS,QAAQ,UAAU,KAAK,CAAC,IAAI,CAAC,KAAK,GAEjF,QAAQ,KAAa,MAAe,MAAM,SAAS,QAAQ,OAAO,CAAC,EAAE,GAAG,CAAC,CACjF;EACD;EACA,SACC,OAAO;CACT;AACD;;;;;;;AAQA,MAAa,gBACZ,MACA,SACA,aACY;CACZ,IAAI,CAAC,MACJ,OAAO;CAER,OAAO,SAAS,MAAM;EAAE;EAAS;CAAS,GAAG,CAAC;AAC/C"}

package/dist/calc/formatCalc.d.ts

@@ -0,0 +1,11 @@
+import { CalcExpression } from "./types.js";
+
+//#region src/calc/formatCalc.d.ts
+/**
+ * Renders a CalcExpression as a human-readable one-line string for the visual expression builder's
+ * live preview. `sourceLabel` resolves a calc source key to its display label (raw key when omitted).
+ */
+declare const formatCalc: (expr: CalcExpression, labelOf: (field: string) => string, sourceLabel?: (key: string) => string) => string;
+//#endregion
+export { formatCalc };
+//# sourceMappingURL=formatCalc.d.ts.map

package/dist/calc/formatCalc.js

@@ -0,0 +1,35 @@
+//#region src/calc/formatCalc.ts
+const OP_GLYPHS = {
+	"+": "+",
+	"-": "−",
+	"*": "×",
+	"/": "÷",
+	"%": "%"
+};
+const wrap = (child, resolvers, wrapTypes = ["op"]) => {
+	const formatted = format(child, resolvers);
+	return wrapTypes.includes(child.type) ? `(${formatted})` : formatted;
+};
+const format = (expr, resolvers) => {
+	switch (expr.type) {
+		case "lit": return String(expr.value);
+		case "ref": return resolvers.labelOf(expr.field);
+		case "neg": return `−${wrap(expr.operand, resolvers, ["op", "neg"])}`;
+		case "op": return `${wrap(expr.left, resolvers)} ${OP_GLYPHS[expr.op]} ${wrap(expr.right, resolvers)}`;
+		case "fn": return `${expr.fn}(${expr.args.map((arg) => format(arg, resolvers)).join(", ")})`;
+		case "source": return resolvers.sourceLabel(expr.source);
+		case "weight": return `weights(${resolvers.labelOf(expr.field)})`;
+	}
+};
+/**
+* Renders a CalcExpression as a human-readable one-line string for the visual expression builder's
+* live preview. `sourceLabel` resolves a calc source key to its display label (raw key when omitted).
+*/
+const formatCalc = (expr, labelOf, sourceLabel = (key) => key) => format(expr, {
+	labelOf,
+	sourceLabel
+});
+//#endregion
+export { formatCalc };
+
+//# sourceMappingURL=formatCalc.js.map

package/dist/calc/formatCalc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatCalc.js","names":[],"sources":["../../src/calc/formatCalc.ts"],"sourcesContent":["import type { CalcExpression, CalcOp } from './types'\n\nconst OP_GLYPHS: Record<CalcOp, string> = {\n\t'+': '+',\n\t'-': '−',\n\t'*': '×',\n\t'/': '÷',\n\t'%': '%',\n}\n\ntype LabelResolvers = {\n\tlabelOf: (field: string) => string\n\tsourceLabel: (key: string) => string\n}\n\nconst wrap = (\n\tchild: CalcExpression,\n\tresolvers: LabelResolvers,\n\twrapTypes: readonly CalcExpression['type'][] = ['op']\n): string => {\n\tconst formatted = format(child, resolvers)\n\treturn wrapTypes.includes(child.type) ? `(${formatted})` : formatted\n}\n\nconst format = (expr: CalcExpression, resolvers: LabelResolvers): string => {\n\tswitch (expr.type) {\n\t\tcase 'lit':\n\t\t\treturn String(expr.value)\n\t\tcase 'ref':\n\t\t\treturn resolvers.labelOf(expr.field)\n\t\tcase 'neg':\n\t\t\t// Parenthesize a nested `neg` operand too, otherwise \"-(-5)\" glues into the ambiguous \"--5\".\n\t\t\treturn `−${wrap(expr.operand, resolvers, ['op', 'neg'])}`\n\t\tcase 'op':\n\t\t\treturn `${wrap(expr.left, resolvers)} ${OP_GLYPHS[expr.op]} ${wrap(expr.right, resolvers)}`\n\t\tcase 'fn':\n\t\t\treturn `${expr.fn}(${expr.args.map((arg) => format(arg, resolvers)).join(', ')})`\n\t\tcase 'source':\n\t\t\treturn resolvers.sourceLabel(expr.source)\n\t\tcase 'weight':\n\t\t\treturn `weights(${resolvers.labelOf(expr.field)})`\n\t}\n}\n\n/**\n * Renders a CalcExpression as a human-readable one-line string for the visual expression builder's\n * live preview. `sourceLabel` resolves a calc source key to its display label (raw key when omitted).\n */\nexport const formatCalc = (\n\texpr: CalcExpression,\n\tlabelOf: (field: string) => string,\n\tsourceLabel: (key: string) => string = (key) => key\n): string => format(expr, { labelOf, sourceLabel })\n"],"mappings":";AAEA,MAAM,YAAoC;CACzC,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;AACN;AAOA,MAAM,QACL,OACA,WACA,YAA+C,CAAC,IAAI,MACxC;CACZ,MAAM,YAAY,OAAO,OAAO,SAAS;CACzC,OAAO,UAAU,SAAS,MAAM,IAAI,IAAI,IAAI,UAAU,KAAK;AAC5D;AAEA,MAAM,UAAU,MAAsB,cAAsC;CAC3E,QAAQ,KAAK,MAAb;EACC,KAAK,OACJ,OAAO,OAAO,KAAK,KAAK;EACzB,KAAK,OACJ,OAAO,UAAU,QAAQ,KAAK,KAAK;EACpC,KAAK,OAEJ,OAAO,IAAI,KAAK,KAAK,SAAS,WAAW,CAAC,MAAM,KAAK,CAAC;EACvD,KAAK,MACJ,OAAO,GAAG,KAAK,KAAK,MAAM,SAAS,EAAE,GAAG,UAAU,KAAK,IAAI,GAAG,KAAK,KAAK,OAAO,SAAS;EACzF,KAAK,MACJ,OAAO,GAAG,KAAK,GAAG,GAAG,KAAK,KAAK,KAAK,QAAQ,OAAO,KAAK,SAAS,CAAC,EAAE,KAAK,IAAI,EAAE;EAChF,KAAK,UACJ,OAAO,UAAU,YAAY,KAAK,MAAM;EACzC,KAAK,UACJ,OAAO,WAAW,UAAU,QAAQ,KAAK,KAAK,EAAE;CAClD;AACD;;;;;AAMA,MAAa,cACZ,MACA,SACA,eAAwC,QAAQ,QACpC,OAAO,MAAM;CAAE;CAAS;AAAY,CAAC"}

package/dist/calc/formatCalcValue.d.ts

@@ -0,0 +1,17 @@
+//#region src/calc/formatCalcValue.d.ts
+/** The calculation field's display settings (`decimals`, `prefix`, `suffix` config fields). */
+type CalcDisplayConfig = {
+  decimals?: unknown;
+  prefix?: unknown;
+  suffix?: unknown;
+};
+/**
+ * Formats a computed calculation value for display: fixed `decimals` when configured, wrapped in
+ * `prefix`/`suffix` exactly as authored (no injected spaces; authors control spacing in their
+ * strings). Shared by the visitor renderer and the definition's `format` so the frontend, admin
+ * answers view, emails, and recall all agree.
+ */
+declare const formatCalcValue: (value: number, config?: CalcDisplayConfig) => string;
+//#endregion
+export { CalcDisplayConfig, formatCalcValue };
+//# sourceMappingURL=formatCalcValue.d.ts.map

package/dist/calc/formatCalcValue.js

@@ -0,0 +1,17 @@
+//#region src/calc/formatCalcValue.ts
+const asDecimals = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 6 ? value : void 0;
+/**
+* Formats a computed calculation value for display: fixed `decimals` when configured, wrapped in
+* `prefix`/`suffix` exactly as authored (no injected spaces; authors control spacing in their
+* strings). Shared by the visitor renderer and the definition's `format` so the frontend, admin
+* answers view, emails, and recall all agree.
+*/
+const formatCalcValue = (value, config) => {
+	const decimals = asDecimals(config?.decimals);
+	const number = decimals !== void 0 ? value.toFixed(decimals) : String(value);
+	return `${typeof config?.prefix === "string" ? config.prefix : ""}${number}${typeof config?.suffix === "string" ? config.suffix : ""}`;
+};
+//#endregion
+export { formatCalcValue };
+
+//# sourceMappingURL=formatCalcValue.js.map

package/dist/calc/formatCalcValue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatCalcValue.js","names":[],"sources":["../../src/calc/formatCalcValue.ts"],"sourcesContent":["/** The calculation field's display settings (`decimals`, `prefix`, `suffix` config fields). */\nexport type CalcDisplayConfig = {\n\tdecimals?: unknown\n\tprefix?: unknown\n\tsuffix?: unknown\n}\n\nconst asDecimals = (value: unknown): number | undefined =>\n\ttypeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 6\n\t\t? value\n\t\t: undefined\n\n/**\n * Formats a computed calculation value for display: fixed `decimals` when configured, wrapped in\n * `prefix`/`suffix` exactly as authored (no injected spaces; authors control spacing in their\n * strings). Shared by the visitor renderer and the definition's `format` so the frontend, admin\n * answers view, emails, and recall all agree.\n */\nexport const formatCalcValue = (value: number, config?: CalcDisplayConfig): string => {\n\tconst decimals = asDecimals(config?.decimals)\n\tconst number = decimals !== undefined ? value.toFixed(decimals) : String(value)\n\tconst prefix = typeof config?.prefix === 'string' ? config.prefix : ''\n\tconst suffix = typeof config?.suffix === 'string' ? config.suffix : ''\n\treturn `${prefix}${number}${suffix}`\n}\n"],"mappings":";AAOA,MAAM,cAAc,UACnB,OAAO,UAAU,YAAY,OAAO,UAAU,KAAK,KAAK,SAAS,KAAK,SAAS,IAC5E,QACA,KAAA;;;;;;;AAQJ,MAAa,mBAAmB,OAAe,WAAuC;CACrF,MAAM,WAAW,WAAW,QAAQ,QAAQ;CAC5C,MAAM,SAAS,aAAa,KAAA,IAAY,MAAM,QAAQ,QAAQ,IAAI,OAAO,KAAK;CAG9E,OAAO,GAFQ,OAAO,QAAQ,WAAW,WAAW,OAAO,SAAS,KAEjD,SADJ,OAAO,QAAQ,WAAW,WAAW,OAAO,SAAS;AAErE"}

package/dist/calc/normalizeCalc.d.ts

@@ -1,8 +1,22 @@
 import { CalcExpression } from "./types.js";
 
 //#region src/calc/normalizeCalc.d.ts
-/** Structural guard: returns a valid CalcExpression if `value` is structurally sound (depth-guarded at 64), otherwise undefined. Never throws. */
-declare const normalizeCalc: (value: unknown) => CalcExpression | undefined;
+/**
+ * The extension names a normalized expression may reference: registered calc source keys and custom
+ * function names (plugin option `calc`). Absent (the default for every un-threaded caller), only the
+ * built-in grammar is valid: `source` nodes, sourced weights, and custom fns all reject.
+ */
+type CalcAllowed = {
+  sources?: ReadonlySet<string>;
+  functions?: ReadonlySet<string>;
+};
+/**
+ * Structural guard: returns a valid CalcExpression if `value` is structurally sound (depth-guarded
+ * at 64), otherwise undefined. Never throws. `allowed` admits registered extension names (source
+ * keys, custom function names); without it only the built-in grammar passes, so an un-threaded
+ * caller can never validate an expression the evaluator has no values for.
+ */
+declare const normalizeCalc: (value: unknown, allowed?: CalcAllowed) => CalcExpression | undefined;
 //#endregion
-export { normalizeCalc };
+export { CalcAllowed, normalizeCalc };
 //# sourceMappingURL=normalizeCalc.d.ts.map

package/dist/calc/normalizeCalc.js

@@ -1,9 +1,8 @@
-import { CALC_FNS, CALC_OPS } from "./types.js";
+import { CALC_OPS, isCalcFn } from "./types.js";
 //#region src/calc/normalizeCalc.ts
 const isOp = (v) => CALC_OPS.includes(v);
-const isFn = (v) => CALC_FNS.includes(v);
 const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-const normalizeNode = (value, depth) => {
+const normalizeNode = (value, depth, allowed) => {
 	if (depth > 64) return void 0;
 	if (!isRecord(value)) return void 0;
 	switch (value.type) {
@@ -26,9 +25,9 @@ const normalizeNode = (value, depth) => {
 		case "op": {
 			const { op, left, right } = value;
 			if (!isOp(op)) return void 0;
-			const l = normalizeNode(left, depth + 1);
+			const l = normalizeNode(left, depth + 1, allowed);
 			if (!l) return void 0;
-			const r = normalizeNode(right, depth + 1);
+			const r = normalizeNode(right, depth + 1, allowed);
 			if (!r) return void 0;
 			return {
 				type: "op",
@@ -38,7 +37,7 @@ const normalizeNode = (value, depth) => {
 			};
 		}
 		case "neg": {
-			const operand = normalizeNode(value.operand, depth + 1);
+			const operand = normalizeNode(value.operand, depth + 1, allowed);
 			if (!operand) return void 0;
 			return {
 				type: "neg",
@@ -47,11 +46,12 @@ const normalizeNode = (value, depth) => {
 		}
 		case "fn": {
 			const { fn, args } = value;
-			if (!isFn(fn)) return void 0;
+			if (typeof fn !== "string") return void 0;
+			if (!isCalcFn(fn) && !allowed?.functions?.has(fn)) return void 0;
 			if (!Array.isArray(args)) return void 0;
 			const normalizedArgs = [];
 			for (const arg of args) {
-				const a = normalizeNode(arg, depth + 1);
+				const a = normalizeNode(arg, depth + 1, allowed);
 				if (!a) return void 0;
 				normalizedArgs.push(a);
 			}
@@ -61,26 +61,48 @@ const normalizeNode = (value, depth) => {
 				args: normalizedArgs
 			};
 		}
+		case "source": {
+			const { source } = value;
+			if (typeof source !== "string") return void 0;
+			if (!allowed?.sources?.has(source)) return void 0;
+			return {
+				type: "source",
+				source
+			};
+		}
 		case "weight": {
-			const { field, weights } = value;
+			const { field, weights, source } = value;
 			if (typeof field !== "string") return void 0;
-			if (!isRecord(weights)) return void 0;
-			const normalizedWeights = {};
-			for (const [k, v] of Object.entries(weights)) {
-				if (typeof v !== "number" || !Number.isFinite(v)) return void 0;
-				normalizedWeights[k] = v;
+			if (source !== void 0) {
+				if (typeof source !== "string" || !allowed?.sources?.has(source)) return void 0;
+			}
+			let normalizedWeights;
+			if (weights !== void 0) {
+				if (!isRecord(weights)) return void 0;
+				normalizedWeights = {};
+				for (const [k, v] of Object.entries(weights)) {
+					if (typeof v !== "number" || !Number.isFinite(v)) return void 0;
+					normalizedWeights[k] = v;
+				}
 			}
+			if (normalizedWeights === void 0 && source === void 0) return void 0;
 			return {
 				type: "weight",
 				field,
-				weights: normalizedWeights
+				...normalizedWeights !== void 0 ? { weights: normalizedWeights } : {},
+				...typeof source === "string" ? { source } : {}
 			};
 		}
 		default: return;
 	}
 };
-/** Structural guard: returns a valid CalcExpression if `value` is structurally sound (depth-guarded at 64), otherwise undefined. Never throws. */
-const normalizeCalc = (value) => normalizeNode(value, 0);
+/**
+* Structural guard: returns a valid CalcExpression if `value` is structurally sound (depth-guarded
+* at 64), otherwise undefined. Never throws. `allowed` admits registered extension names (source
+* keys, custom function names); without it only the built-in grammar passes, so an un-threaded
+* caller can never validate an expression the evaluator has no values for.
+*/
+const normalizeCalc = (value, allowed) => normalizeNode(value, 0, allowed);
 //#endregion
 export { normalizeCalc };