@happyvertical/smrt-fields 0.40.61 → 0.40.62

package/dist/svelte/components/FieldPolicySuggestionQueue.svelte

@@ -0,0 +1,135 @@
+<script lang="ts">
+/** Accessible, host-transport-neutral review queue for pending suggestions. */
+import { Button } from '@happyvertical/smrt-ui/ui';
+import {
+  type FieldPolicySuggestion,
+  type FieldPolicySuggestionAdapter,
+  fieldPolicySuggestionEvidence,
+  parsePendingFieldPolicySuggestions,
+} from '../suggestions.js';
+
+export interface FieldPolicySuggestionQueueProps {
+  adapter: FieldPolicySuggestionAdapter;
+  objectRefs?: readonly string[];
+  heading?: string;
+  onchanged?: () => void;
+}
+
+let {
+  adapter,
+  objectRefs,
+  heading = 'Pending field suggestions',
+  onchanged,
+}: FieldPolicySuggestionQueueProps = $props();
+
+let suggestions = $state<FieldPolicySuggestion[]>([]);
+let total = $state(0);
+let loading = $state(false);
+let busyId = $state<string | null>(null);
+let error = $state<string | null>(null);
+let generation = 0;
+
+async function load(): Promise<void> {
+  const token = ++generation;
+  loading = true;
+  error = null;
+  try {
+    const result = parsePendingFieldPolicySuggestions(
+      await adapter.pendingSuggestions(
+        objectRefs?.length ? { objectRefs } : undefined,
+      ),
+    );
+    if (token !== generation) return;
+    suggestions = result.suggestions;
+    total = result.total;
+  } catch (cause) {
+    if (token !== generation) return;
+    suggestions = [];
+    total = 0;
+    error =
+      cause instanceof Error
+        ? cause.message
+        : 'Unable to load pending field suggestions.';
+  } finally {
+    if (token === generation) loading = false;
+  }
+}
+
+async function decide(
+  suggestion: FieldPolicySuggestion,
+  decision: 'approve' | 'dismiss',
+): Promise<void> {
+  if (busyId) return;
+  busyId = suggestion.id;
+  error = null;
+  try {
+    if (decision === 'approve') {
+      await adapter.acceptSuggestion({ id: suggestion.id });
+    } else {
+      await adapter.dismissSuggestion({ id: suggestion.id });
+    }
+    await load();
+    onchanged?.();
+  } catch (cause) {
+    error =
+      cause instanceof Error
+        ? cause.message
+        : 'Unable to update this field suggestion.';
+  } finally {
+    busyId = null;
+  }
+}
+
+$effect(() => {
+  adapter;
+  objectRefs;
+  void load();
+});
+
+function description(suggestion: FieldPolicySuggestion): string {
+  return suggestion.kind === 'promote'
+    ? `Promote ${suggestion.fieldName} to the basic form.`
+    : `Set an organization default for ${suggestion.fieldName}.`;
+}
+</script>
+
+<section class="field-policy-suggestion-queue" aria-label={heading}>
+  <header>
+    <h2>{heading}</h2>
+    {#if !loading}<span class="field-policy-suggestion-queue__count">{total}</span>{/if}
+  </header>
+  {#if loading}
+    <p role="status" aria-live="polite">Loading pending suggestions…</p>
+  {:else if error}
+    <p role="alert">{error}</p>
+  {:else if suggestions.length === 0}
+    <p>No pending field suggestions.</p>
+  {:else}
+    <ul>
+      {#each suggestions as suggestion (suggestion.id)}
+        <li>
+          <article>
+            <h3>{suggestion.objectRef} · {suggestion.fieldName}</h3>
+            <p>{description(suggestion)}</p>
+            <p>{fieldPolicySuggestionEvidence(suggestion)}</p>
+            <div class="field-policy-suggestion-queue__actions">
+              <Button type="button" disabled={busyId !== null} onclick={() => decide(suggestion, 'approve')}>Approve</Button>
+              <Button type="button" variant="ghost" disabled={busyId !== null} onclick={() => decide(suggestion, 'dismiss')}>Dismiss</Button>
+            </div>
+          </article>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+</section>
+
+<style>
+  .field-policy-suggestion-queue { display: grid; gap: var(--smrt-spacing-3, 0.75rem); }
+  .field-policy-suggestion-queue header { align-items: center; display: flex; gap: var(--smrt-spacing-2, 0.5rem); }
+  .field-policy-suggestion-queue h2, .field-policy-suggestion-queue h3 { margin: 0; }
+  .field-policy-suggestion-queue__count { border-radius: 999px; background: var(--smrt-color-secondary-container, #e8def8); min-inline-size: 1.5rem; padding: 0.125rem 0.4rem; text-align: center; }
+  .field-policy-suggestion-queue ul { display: grid; gap: var(--smrt-spacing-3, 0.75rem); list-style: none; margin: 0; padding: 0; }
+  .field-policy-suggestion-queue article { border: 1px solid var(--smrt-color-outline-variant, currentColor); border-radius: var(--smrt-radius-small, 0.25rem); display: grid; gap: var(--smrt-spacing-2, 0.5rem); padding: var(--smrt-spacing-3, 0.75rem); }
+  .field-policy-suggestion-queue article p { margin: 0; }
+  .field-policy-suggestion-queue__actions { display: flex; flex-wrap: wrap; gap: var(--smrt-spacing-2, 0.5rem); }
+</style>

package/dist/svelte/components/FieldPolicySuggestionQueue.svelte.d.ts

@@ -0,0 +1,11 @@
+import { type FieldPolicySuggestionAdapter } from '../suggestions.js';
+export interface FieldPolicySuggestionQueueProps {
+    adapter: FieldPolicySuggestionAdapter;
+    objectRefs?: readonly string[];
+    heading?: string;
+    onchanged?: () => void;
+}
+declare const FieldPolicySuggestionQueue: import("svelte").Component<FieldPolicySuggestionQueueProps, {}, "">;
+type FieldPolicySuggestionQueue = ReturnType<typeof FieldPolicySuggestionQueue>;
+export default FieldPolicySuggestionQueue;
+//# sourceMappingURL=FieldPolicySuggestionQueue.svelte.d.ts.map

package/dist/svelte/components/FieldPolicySuggestionQueue.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldPolicySuggestionQueue.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/FieldPolicySuggestionQueue.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,4BAA4B,EAGlC,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,4BAA4B,CAAC;IACtC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAuHD,QAAA,MAAM,0BAA0B,qEAAwC,CAAC;AACzE,KAAK,0BAA0B,GAAG,UAAU,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAChF,eAAe,0BAA0B,CAAC"}

package/dist/svelte/components/ObjectForm.svelte

@@ -21,6 +21,11 @@ import {
   type ObjectFormFieldDefinition,
   type ObjectFormFieldSnippetProps,
 } from '../types.js';
+import {
+  collectFieldUsageEntries,
+  type FieldUsageReporter,
+  reportFieldUsage,
+} from '../usage-capture.js';
 import AdvancedFields from './AdvancedFields.svelte';
 import FieldInput from './FieldInput.svelte';
 import FieldPolicyGearButton from './FieldPolicyGearButton.svelte';
@@ -57,10 +62,23 @@ export interface ObjectFormProps {
   renderers?: Readonly<Record<string, Snippet<[ObjectFormFieldSnippetProps]>>>;
   /** Optional controls rendered after the policy-ordered fields inside the form. */
   actions?: Snippet;
+  /**
+   * Optional telemetry transport. It runs only when `onsubmit` explicitly
+   * resolves `true` after persistence; identity and field sensitivity remain
+   * server-derived.
+   */
+  usageReporter?: FieldUsageReporter;
   class?: string;
-  onsubmit?: (event: SubmitEvent) => void;
+  /** Return true only after the host has persisted this record successfully. */
+  onsubmit?: ObjectFormSubmitHandler;
 }
 
+// biome-ignore lint/suspicious/noConfusingVoidType: void handlers remain a supported legacy integration and never acknowledge persistence.
+export type ObjectFormSubmitAcknowledgement = boolean | void;
+export type ObjectFormSubmitHandler = (
+  event: SubmitEvent,
+) => ObjectFormSubmitAcknowledgement | Promise<ObjectFormSubmitAcknowledgement>;
+
 let {
   objectRef,
   fields = undefined,
@@ -74,6 +92,7 @@ let {
   inputRegistry,
   renderers = {},
   actions,
+  usageReporter,
   class: className = '',
   onsubmit,
 }: ObjectFormProps = $props();
@@ -201,6 +220,76 @@ function fieldId(name: string): string {
   return `${formInstanceId}-${name}`;
 }
 
+function captureUsage(values: Readonly<Record<string, unknown>>): void {
+  if (!resolvedPolicy) return;
+  reportFieldUsage(
+    usageReporter,
+    collectFieldUsageEntries({
+      objectRef,
+      values,
+      // Hidden fields are not submitted user inputs. Basic and advanced fields
+      // are included even when a value matches the default so the server's
+      // dominance calculation has a complete denominator.
+      fields: Object.fromEntries(
+        formFields
+          .filter(
+            (field) =>
+              resolvedPolicy.fields[field.name].visibility !== 'hidden',
+          )
+          .map((field) => [field.name, field.definition.type]),
+      ),
+      defaults: Object.fromEntries(
+        formFields
+          .filter(
+            (field) =>
+              resolvedPolicy.fields[field.name].visibility !== 'hidden',
+          )
+          .map((field) => {
+            const resolved = resolvedPolicy.fields[field.name];
+            return [
+              field.name,
+              {
+                hasDefault: resolved.hasDefault,
+                defaultValue: resolved.defaultValue,
+              },
+            ];
+          }),
+      ),
+    }),
+  );
+}
+
+async function handleSubmit(event: SubmitEvent): Promise<void> {
+  if (invalidFields.size > 0) {
+    event.preventDefault();
+    return;
+  }
+  if (!onsubmit) return;
+  // A successful create commonly replaces the bound record before its
+  // persistence promise resolves. Snapshot before awaiting so usage describes
+  // the fields that were submitted, not the newly cleared next-record state.
+  const submittedValues = snapshotUsageValues(value);
+  try {
+    // Form prevents native navigation itself, so persistence acknowledgement
+    // must be explicit rather than inferred from event.defaultPrevented.
+    if ((await onsubmit(event)) === true) captureUsage(submittedValues);
+  } catch {
+    // The host owns persistence errors; rejected submissions never emit usage.
+  }
+}
+
+function snapshotUsageValues(
+  record: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  try {
+    return structuredClone(record);
+  } catch {
+    // Generated form values are wire-safe, but retain a shallow fallback for
+    // host extensions that add an uncloneable value outside telemetry fields.
+    return { ...record };
+  }
+}
+
 // Apply policy defaults to a create record once, before a user can interact
 // with any control. This preserves JSON and boolean defaults (which cannot be
 // faithfully inferred from generic DOM string assignment) and means callers
@@ -330,7 +419,7 @@ function inputFor(field: ObjectFormField): FieldInputComponent {
       <div class="object-form__gear"><FieldPolicyGearButton /></div>
     {/if}
   {/if}
-  <Form class="object-form {className}" onsubmit={(event) => { if (invalidFields.size > 0) { event.preventDefault(); return; } onsubmit?.(event); }}>
+  <Form class="object-form {className}" onsubmit={handleSubmit}>
     {@render renderGroups(basicGroups)}
     {#if advancedGroups.length > 0}
       <AdvancedFields open>

package/dist/svelte/components/ObjectForm.svelte.d.ts

@@ -2,6 +2,9 @@ import type { Component, Snippet } from 'svelte';
 import type { ResolvedObjectFieldPolicy } from '../../types.js';
 import type { FieldInputRegistry } from '../input-registry.js';
 import { type ObjectFormFieldDefinition, type ObjectFormFieldSnippetProps } from '../types.js';
+import { type FieldUsageReporter } from '../usage-capture.js';
+export type ObjectFormSubmitAcknowledgement = boolean | void;
+export type ObjectFormSubmitHandler = (event: SubmitEvent) => ObjectFormSubmitAcknowledgement | Promise<ObjectFormSubmitAcknowledgement>;
 export interface ObjectFormProps {
     objectRef: string;
     /**
@@ -31,8 +34,15 @@ export interface ObjectFormProps {
     renderers?: Readonly<Record<string, Snippet<[ObjectFormFieldSnippetProps]>>>;
     /** Optional controls rendered after the policy-ordered fields inside the form. */
     actions?: Snippet;
+    /**
+     * Optional telemetry transport. It runs only when `onsubmit` explicitly
+     * resolves `true` after persistence; identity and field sensitivity remain
+     * server-derived.
+     */
+    usageReporter?: FieldUsageReporter;
     class?: string;
-    onsubmit?: (event: SubmitEvent) => void;
+    /** Return true only after the host has persisted this record successfully. */
+    onsubmit?: ObjectFormSubmitHandler;
 }
 declare const ObjectForm: Component<ObjectFormProps, {}, "value">;
 type ObjectForm = ReturnType<typeof ObjectForm>;

package/dist/svelte/components/ObjectForm.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ObjectForm.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/ObjectForm.svelte.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,KAAK,EAEV,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EACjC,MAAM,aAAa,CAAC;AASrB,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC;IAC7D,mFAAmF;IACnF,MAAM,CAAC,EAAE,yBAAyB,CAAC;IACnC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,uEAAuE;IACvE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yEAAyE;IACzE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7E,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CACzC;AAsSD,QAAA,MAAM,UAAU,yCAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}
+{"version":3,"file":"ObjectForm.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/ObjectForm.svelte.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,KAAK,EAEV,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EACjC,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,qBAAqB,CAAC;AAU7B,MAAM,MAAM,+BAA+B,GAAG,OAAO,GAAG,IAAI,CAAC;AAC7D,MAAM,MAAM,uBAAuB,GAAG,CACpC,KAAK,EAAE,WAAW,KACf,+BAA+B,GAAG,OAAO,CAAC,+BAA+B,CAAC,CAAC;AAEhF,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC;IAC7D,mFAAmF;IACnF,MAAM,CAAC,EAAE,yBAAyB,CAAC;IACnC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,uEAAuE;IACvE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yEAAyE;IACzE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7E,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,uBAAuB,CAAC;CACpC;AAgXD,QAAA,MAAM,UAAU,yCAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/svelte/gear-context.svelte.d.ts

@@ -4,6 +4,8 @@ export interface FieldPolicyGearController {
     readonly error: string | null;
     readonly open: boolean;
     readonly canEdit: boolean;
+    /** Pending reviewed suggestions for this form's object, when configured. */
+    readonly pendingSuggestionCount: number;
     show(): void;
     hide(): void;
     reload(): Promise<void>;

package/dist/svelte/gear-context.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gear-context.svelte.d.ts","sourceRoot":"","sources":["../../src/svelte/gear-context.svelte.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,IAAI,IAAI,IAAI,CAAC;IACb,IAAI,IAAI,IAAI,CAAC;IACb,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAID,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,yBAAyB,GACpC,IAAI,CAEN;AAED,wBAAgB,yBAAyB,IAAI,yBAAyB,CAQrE;AAED,wBAAgB,4BAA4B,IACxC,yBAAyB,GACzB,SAAS,CAIZ"}
+{"version":3,"file":"gear-context.svelte.d.ts","sourceRoot":"","sources":["../../src/svelte/gear-context.svelte.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,IAAI,IAAI,IAAI,CAAC;IACb,IAAI,IAAI,IAAI,CAAC;IACb,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAID,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,yBAAyB,GACpC,IAAI,CAEN;AAED,wBAAgB,yBAAyB,IAAI,yBAAyB,CAQrE;AAED,wBAAgB,4BAA4B,IACxC,yBAAyB,GACzB,SAAS,CAIZ"}

package/dist/svelte/index.d.ts

@@ -21,22 +21,25 @@ import FieldPolicyEditor from './components/FieldPolicyEditor.svelte';
 import FieldPolicyGearButton from './components/FieldPolicyGearButton.svelte';
 import FieldPolicyGearProvider from './components/FieldPolicyGearProvider.svelte';
 import FieldPolicyProvider from './components/FieldPolicyProvider.svelte';
+import FieldPolicySuggestionQueue from './components/FieldPolicySuggestionQueue.svelte';
 import FormHelp from './components/FormHelp.svelte';
 import ModeSwitch from './components/ModeSwitch.svelte';
 import ObjectForm from './components/ObjectForm.svelte';
 import ObjectFormSourceProvider from './components/ObjectFormSourceProvider.svelte';
 import PolicyField from './components/PolicyField.svelte';
-export { AdvancedFields, FieldPolicyControlPanel, FieldPolicyEditor, FieldPolicyGearButton, FieldPolicyGearProvider, FieldPolicyProvider, FormHelp, ModeSwitch, ObjectForm, ObjectFormSourceProvider, PolicyField, };
+export { AdvancedFields, FieldPolicyControlPanel, FieldPolicyEditor, FieldPolicyGearButton, FieldPolicyGearProvider, FieldPolicyProvider, FieldPolicySuggestionQueue, FormHelp, ModeSwitch, ObjectForm, ObjectFormSourceProvider, PolicyField, };
 export type AdvancedFieldsProps = ComponentProps<typeof AdvancedFields>;
 export type FieldPolicyProviderProps = ComponentProps<typeof FieldPolicyProvider>;
 export type FormHelpProps = ComponentProps<typeof FormHelp>;
 export type ModeSwitchProps = ComponentProps<typeof ModeSwitch>;
 export type ObjectFormProps = ComponentProps<typeof ObjectForm>;
+export type { ObjectFormSubmitAcknowledgement, ObjectFormSubmitHandler, } from './components/ObjectForm.svelte';
 export type ObjectFormSourceProviderProps = ComponentProps<typeof ObjectFormSourceProvider>;
 export type FieldPolicyEditorProps = ComponentProps<typeof FieldPolicyEditor>;
 export type FieldPolicyControlPanelProps = ComponentProps<typeof FieldPolicyControlPanel>;
 export type FieldPolicyGearButtonProps = ComponentProps<typeof FieldPolicyGearButton>;
 export type FieldPolicyGearProviderProps = ComponentProps<typeof FieldPolicyGearProvider>;
+export type FieldPolicySuggestionQueueProps = ComponentProps<typeof FieldPolicySuggestionQueue>;
 export type PolicyFieldProps = ComponentProps<typeof PolicyField>;
 export type { FieldPolicyCatalogObjectSummary, FieldPolicyDetailItem, FieldPolicySettingsCatalogData, FieldPolicySettingsCatalogPage, FieldPolicySummaryItem, } from '../settings-catalog.js';
 export type { ResolvedFieldPolicy, ResolvedObjectFieldPolicy, } from '../types.js';
@@ -54,5 +57,7 @@ export { resolveObjectFormFields } from './object-form.js';
 export { assertObjectFormCollectionDefinition, ObjectFormSourceRegistry, } from './object-form-source.svelte.js';
 export type { FieldPolicyControlPanelAdapter, FieldPolicyFieldRollup, FieldPolicyLayerCell, } from './settings-catalog.js';
 export { auditObjectRefs, decorateCatalogItem, decorateCatalogPage, fieldPolicyControlPanelNavItem, fieldPolicyRollup, MAX_FIELD_POLICY_AUDIT_OBJECT_REFS, orgRowIdsForObject, prunableDriftRows, } from './settings-catalog.js';
+export { type FieldPolicySuggestion, type FieldPolicySuggestionAdapter, type FieldPolicySuggestionKind, fieldPolicySuggestionEvidence, parsePendingFieldPolicySuggestions, } from './suggestions.js';
 export type { FieldInputProps, ObjectFormCollectionDefinition, ObjectFormField, ObjectFormFieldDefinition, ObjectFormFieldSnippetProps, ObjectFormPolicyClient, ObjectFormResolvedSource, ObjectFormSource, ObjectFormWireType, PolicyFieldSnippetProps, } from './types.js';
+export { type CollectFieldUsageEntriesOptions, canCaptureFieldUsageValue, collectFieldUsageEntries, type FieldUsageDefault, type FieldUsageEntry, type FieldUsageReporter, type FieldUsageWireType, fieldUsageValuesEqual, isBlankFieldValue, reportFieldUsage, } from './usage-capture.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/svelte/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/svelte/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/svelte/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,cAAc,MAAM,oCAAoC,CAAC;AAChE,OAAO,uBAAuB,MAAM,6CAA6C,CAAC;AAClF,OAAO,iBAAiB,MAAM,uCAAuC,CAAC;AACtE,OAAO,qBAAqB,MAAM,2CAA2C,CAAC;AAC9E,OAAO,uBAAuB,MAAM,6CAA6C,CAAC;AAClF,OAAO,mBAAmB,MAAM,yCAAyC,CAAC;AAC1E,OAAO,0BAA0B,MAAM,gDAAgD,CAAC;AACxF,OAAO,QAAQ,MAAM,8BAA8B,CAAC;AACpD,OAAO,UAAU,MAAM,gCAAgC,CAAC;AACxD,OAAO,UAAU,MAAM,gCAAgC,CAAC;AACxD,OAAO,wBAAwB,MAAM,8CAA8C,CAAC;AACpF,OAAO,WAAW,MAAM,iCAAiC,CAAC;AAG1D,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,QAAQ,EACR,UAAU,EACV,UAAU,EACV,wBAAwB,EACxB,WAAW,GACZ,CAAC;AAGF,MAAM,MAAM,mBAAmB,GAAG,cAAc,CAAC,OAAO,cAAc,CAAC,CAAC;AACxE,MAAM,MAAM,wBAAwB,GAAG,cAAc,CACnD,OAAO,mBAAmB,CAC3B,CAAC;AACF,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC,OAAO,UAAU,CAAC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC,OAAO,UAAU,CAAC,CAAC;AAChE,YAAY,EACV,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,gCAAgC,CAAC;AACxC,MAAM,MAAM,6BAA6B,GAAG,cAAc,CACxD,OAAO,wBAAwB,CAChC,CAAC;AACF,MAAM,MAAM,sBAAsB,GAAG,cAAc,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC9E,MAAM,MAAM,4BAA4B,GAAG,cAAc,CACvD,OAAO,uBAAuB,CAC/B,CAAC;AACF,MAAM,MAAM,0BAA0B,GAAG,cAAc,CACrD,OAAO,qBAAqB,CAC7B,CAAC;AACF,MAAM,MAAM,4BAA4B,GAAG,cAAc,CACvD,OAAO,uBAAuB,CAC/B,CAAC;AACF,MAAM,MAAM,+BAA+B,GAAG,cAAc,CAC1D,OAAO,0BAA0B,CAClC,CAAC;AACF,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC,OAAO,WAAW,CAAC,CAAC;AAElE,YAAY,EACV,+BAA+B,EAC/B,qBAAqB,EACrB,8BAA8B,EAC9B,8BAA8B,EAC9B,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EACV,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,uBAAuB,EACvB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,yBAAyB,EACzB,oBAAoB,EACpB,oBAAoB,EACpB,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,8BAA8B,EAC9B,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,EAChB,wBAAwB,EACxB,iBAAiB,EACjB,4BAA4B,EAC5B,2BAA2B,EAC3B,WAAW,EACX,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EACL,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EACL,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,8BAA8B,EAC9B,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,8BAA8B,EAC9B,iBAAiB,EACjB,kCAAkC,EAClC,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,EAC9B,6BAA6B,EAC7B,kCAAkC,GACnC,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,eAAe,EACf,8BAA8B,EAC9B,eAAe,EACf,yBAAyB,EACzB,2BAA2B,EAC3B,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,+BAA+B,EACpC,yBAAyB,EACzB,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC"}

package/dist/svelte/index.js

@@ -20,13 +20,14 @@ import FieldPolicyEditor from './components/FieldPolicyEditor.svelte';
 import FieldPolicyGearButton from './components/FieldPolicyGearButton.svelte';
 import FieldPolicyGearProvider from './components/FieldPolicyGearProvider.svelte';
 import FieldPolicyProvider from './components/FieldPolicyProvider.svelte';
+import FieldPolicySuggestionQueue from './components/FieldPolicySuggestionQueue.svelte';
 import FormHelp from './components/FormHelp.svelte';
 import ModeSwitch from './components/ModeSwitch.svelte';
 import ObjectForm from './components/ObjectForm.svelte';
 import ObjectFormSourceProvider from './components/ObjectFormSourceProvider.svelte';
 import PolicyField from './components/PolicyField.svelte';
 // Components
-export { AdvancedFields, FieldPolicyControlPanel, FieldPolicyEditor, FieldPolicyGearButton, FieldPolicyGearProvider, FieldPolicyProvider, FormHelp, ModeSwitch, ObjectForm, ObjectFormSourceProvider, PolicyField, };
+export { AdvancedFields, FieldPolicyControlPanel, FieldPolicyEditor, FieldPolicyGearButton, FieldPolicyGearProvider, FieldPolicyProvider, FieldPolicySuggestionQueue, FormHelp, ModeSwitch, ObjectForm, ObjectFormSourceProvider, PolicyField, };
 // Context types and accessors
 export { getFieldPolicyContext, setFieldPolicyContext, tryGetFieldPolicyContext, } from './context.svelte.js';
 export { policyToVisibleColumnIds } from './data-table.js';
@@ -36,3 +37,5 @@ export { createFieldInputRegistry, FieldInputRegistry, } from './input-registry.
 export { resolveObjectFormFields } from './object-form.js';
 export { assertObjectFormCollectionDefinition, ObjectFormSourceRegistry, } from './object-form-source.svelte.js';
 export { auditObjectRefs, decorateCatalogItem, decorateCatalogPage, fieldPolicyControlPanelNavItem, fieldPolicyRollup, MAX_FIELD_POLICY_AUDIT_OBJECT_REFS, orgRowIdsForObject, prunableDriftRows, } from './settings-catalog.js';
+export { fieldPolicySuggestionEvidence, parsePendingFieldPolicySuggestions, } from './suggestions.js';
+export { canCaptureFieldUsageValue, collectFieldUsageEntries, fieldUsageValuesEqual, isBlankFieldValue, reportFieldUsage, } from './usage-capture.js';

package/dist/svelte/suggestions.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Structural browser contracts for field-policy suggestion review.
+ *
+ * These types intentionally omit tenant, user, authorization, and field
+ * sensitivity data. Hosts bind methods to authenticated generated clients;
+ * the server derives identity and validates every action.
+ */
+export type FieldPolicySuggestionKind = 'promote' | 'default';
+export interface FieldPolicySuggestion {
+    id: string;
+    objectRef: string;
+    fieldName: string;
+    kind: FieldPolicySuggestionKind;
+    proposedValue: string | null;
+    evidence: Readonly<Record<string, unknown>>;
+}
+export interface FieldPolicySuggestionAdapter {
+    pendingSuggestions(input?: {
+        objectRefs?: readonly string[];
+    }): Promise<unknown>;
+    acceptSuggestion(input: {
+        id: string;
+    }): Promise<unknown>;
+    dismissSuggestion(input: {
+        id: string;
+    }): Promise<unknown>;
+}
+/**
+ * Validate generated custom-action output at the browser boundary. A malformed
+ * response is an error, never an empty queue that could conceal work.
+ */
+export declare function parsePendingFieldPolicySuggestions(value: unknown): {
+    suggestions: FieldPolicySuggestion[];
+    total: number;
+};
+/** Human-readable evidence without assuming a server-side evidence schema. */
+export declare function fieldPolicySuggestionEvidence(suggestion: FieldPolicySuggestion): string;
+//# sourceMappingURL=suggestions.d.ts.map

package/dist/svelte/suggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestions.d.ts","sourceRoot":"","sources":["../../src/svelte/suggestions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,yBAAyB,CAAC;IAChC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,4BAA4B;IAC3C,kBAAkB,CAAC,KAAK,CAAC,EAAE;QACzB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAChC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrB,gBAAgB,CAAC,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,iBAAiB,CAAC,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5D;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,OAAO,GAAG;IAClE,WAAW,EAAE,qBAAqB,EAAE,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;CACf,CAsBA;AAmCD,8EAA8E;AAC9E,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,qBAAqB,GAChC,MAAM,CASR"}

package/dist/svelte/suggestions.js

@@ -0,0 +1,68 @@
+/**
+ * Structural browser contracts for field-policy suggestion review.
+ *
+ * These types intentionally omit tenant, user, authorization, and field
+ * sensitivity data. Hosts bind methods to authenticated generated clients;
+ * the server derives identity and validates every action.
+ */
+/**
+ * Validate generated custom-action output at the browser boundary. A malformed
+ * response is an error, never an empty queue that could conceal work.
+ */
+export function parsePendingFieldPolicySuggestions(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    const candidate = value;
+    const total = candidate.total;
+    if (!Array.isArray(candidate.suggestions) ||
+        typeof total !== 'number' ||
+        !Number.isSafeInteger(total) ||
+        total < 0) {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    const suggestions = candidate.suggestions.map(parseSuggestion);
+    if (total < suggestions.length) {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    return { suggestions, total };
+}
+function parseSuggestion(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    const candidate = value;
+    if (typeof candidate.id !== 'string' ||
+        typeof candidate.objectRef !== 'string' ||
+        typeof candidate.fieldName !== 'string' ||
+        (candidate.kind !== 'promote' && candidate.kind !== 'default') ||
+        (candidate.proposedValue !== null &&
+            typeof candidate.proposedValue !== 'string') ||
+        !isRecord(candidate.evidence) ||
+        (candidate.status !== undefined && candidate.status !== 'pending')) {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    return {
+        id: candidate.id,
+        objectRef: candidate.objectRef,
+        fieldName: candidate.fieldName,
+        kind: candidate.kind,
+        proposedValue: candidate.proposedValue,
+        evidence: candidate.evidence,
+    };
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** Human-readable evidence without assuming a server-side evidence schema. */
+export function fieldPolicySuggestionEvidence(suggestion) {
+    const summary = suggestion.evidence.summary;
+    if (typeof summary === 'string' && summary.trim())
+        return summary;
+    const distinctUsers = suggestion.evidence.distinctUsers;
+    const setCount = suggestion.evidence.setCount;
+    if (typeof distinctUsers === 'number' && typeof setCount === 'number') {
+        return `${distinctUsers} users set this field ${setCount} times.`;
+    }
+    return 'Based on recent organization field usage.';
+}

package/dist/svelte/usage-capture.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Browser-safe usage capture primitives for the field-policy learning loop.
+ *
+ * Hosts own the authenticated transport. This module deliberately carries no
+ * tenant, user, permission, or field-sensitivity information: the server
+ * derives all of that from its ambient context and live object registry.
+ */
+/** One submitted field value sent to the host's usage transport. */
+export interface FieldUsageEntry {
+    objectRef: string;
+    fieldName: string;
+    value?: unknown;
+    /** Optional value-less hint; normal ObjectForm capture sends the value. */
+    matchedDefault?: boolean;
+}
+/** Resolved default metadata used only for a value-less count signal. */
+export interface FieldUsageDefault {
+    hasDefault: boolean;
+    defaultValue: unknown;
+}
+/**
+ * Structural host transport for the counters collection's batched action.
+ * A reporter must never be allowed to affect a successful form submission.
+ */
+export interface FieldUsageReporter {
+    reportUsage(input: {
+        entries: readonly FieldUsageEntry[];
+    }): unknown;
+}
+export interface CollectFieldUsageEntriesOptions {
+    objectRef: string;
+    values: Readonly<Record<string, unknown>>;
+    /**
+     * Rendered field names and their persisted browser wire type. The type is
+     * used only to minimize value transit — it is never a sensitivity or
+     * authorization decision.
+     */
+    fields?: Readonly<Record<string, FieldUsageWireType>>;
+    /**
+     * Resolved defaults for rendered fields. For count-only values, a matching
+     * default is sent as a positive hint so the server does not treat it as a
+     * deviation. Absent or non-matching defaults deliberately send no hint.
+     */
+    defaults?: Readonly<Record<string, FieldUsageDefault>>;
+}
+export type FieldUsageWireType = 'text' | 'integer' | 'decimal' | 'boolean' | 'datetime' | 'json' | 'foreignKey' | 'crossPackageRef';
+/** Values may transit only for bounded, identifier-like wire types. */
+export declare function canCaptureFieldUsageValue(type: FieldUsageWireType | undefined): boolean;
+/**
+ * Collect every non-blank submitted field, including values matching a
+ * resolved default. Values transit only for bounded boolean/reference fields;
+ * free text, numbers, dates, and JSON emit count-only signals. Capturing only
+ * deviations would make the default's dominance denominator disappear. The
+ * server still derives eligibility, sensitivity, and every aggregate.
+ */
+export declare function collectFieldUsageEntries(options: CollectFieldUsageEntriesOptions): FieldUsageEntry[];
+/** Zero and false are submissions; only absent/null/empty-string values are not. */
+export declare function isBlankFieldValue(value: unknown): boolean;
+/** JSON-safe equality for the count-only default-match hint. */
+export declare function fieldUsageValuesEqual(left: unknown, right: unknown): boolean;
+/** Fire-and-forget by design: metrics transport failures never reject submit. */
+export declare function reportFieldUsage(reporter: FieldUsageReporter | undefined, entries: readonly FieldUsageEntry[]): void;
+//# sourceMappingURL=usage-capture.d.ts.map

package/dist/svelte/usage-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-capture.d.ts","sourceRoot":"","sources":["../../src/svelte/usage-capture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC;CACtE;AAED,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACtD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;CACxD;AAED,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,SAAS,GACT,SAAS,GACT,SAAS,GACT,UAAU,GACV,MAAM,GACN,YAAY,GACZ,iBAAiB,CAAC;AAEtB,uEAAuE;AACvE,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,kBAAkB,GAAG,SAAS,GACnC,OAAO,CAIT;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,+BAA+B,GACvC,eAAe,EAAE,CAyBnB;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED,gEAAgE;AAChE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAO5E;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,kBAAkB,GAAG,SAAS,EACxC,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,IAAI,CASN"}

package/dist/svelte/usage-capture.js

@@ -0,0 +1,61 @@
+/** Values may transit only for bounded, identifier-like wire types. */
+export function canCaptureFieldUsageValue(type) {
+    return (type === 'boolean' || type === 'foreignKey' || type === 'crossPackageRef');
+}
+/**
+ * Collect every non-blank submitted field, including values matching a
+ * resolved default. Values transit only for bounded boolean/reference fields;
+ * free text, numbers, dates, and JSON emit count-only signals. Capturing only
+ * deviations would make the default's dominance denominator disappear. The
+ * server still derives eligibility, sensitivity, and every aggregate.
+ */
+export function collectFieldUsageEntries(options) {
+    const fields = options.fields ??
+        Object.fromEntries(Object.keys(options.values).map((fieldName) => [fieldName, undefined]));
+    const entries = [];
+    for (const [fieldName, type] of Object.entries(fields)) {
+        const value = options.values[fieldName];
+        if (isBlankFieldValue(value))
+            continue;
+        if (canCaptureFieldUsageValue(type)) {
+            entries.push({ objectRef: options.objectRef, fieldName, value });
+            continue;
+        }
+        const fieldDefault = options.defaults?.[fieldName];
+        entries.push({
+            objectRef: options.objectRef,
+            fieldName,
+            ...(fieldDefault?.hasDefault &&
+                fieldUsageValuesEqual(value, fieldDefault.defaultValue)
+                ? { matchedDefault: true }
+                : {}),
+        });
+    }
+    return entries;
+}
+/** Zero and false are submissions; only absent/null/empty-string values are not. */
+export function isBlankFieldValue(value) {
+    return value === undefined || value === null || value === '';
+}
+/** JSON-safe equality for the count-only default-match hint. */
+export function fieldUsageValuesEqual(left, right) {
+    if (left === right)
+        return true;
+    try {
+        return JSON.stringify(left) === JSON.stringify(right);
+    }
+    catch {
+        return false;
+    }
+}
+/** Fire-and-forget by design: metrics transport failures never reject submit. */
+export function reportFieldUsage(reporter, entries) {
+    if (!reporter || entries.length === 0)
+        return;
+    try {
+        void Promise.resolve(reporter.reportUsage({ entries })).catch(() => undefined);
+    }
+    catch {
+        // A synchronous host adapter failure is non-fatal by the same contract.
+    }
+}