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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @10x-media/form-builder
 
+## 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 };