Document secure storage behavior

Describe password exclusions, debounced autosaves, and typed storage error events across the README and package metadata.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: aarongustafson

README.md

@@ -5,10 +5,11 @@
 A web component that stores (and restores) values within the first form it wraps.
 
 It is designed for crash recovery and interrupted sessions:
-- Saves form field values to `localStorage` as users type.
+- Debounces saves to `localStorage` as users type.
 - Restores values when the page is loaded again.
 - Clears saved values after a successful submit flow.
 - Optionally retains selected fields after submit.
+- Never saves or restores password fields.
 
 ## Demo
 
@@ -150,14 +151,50 @@ Where `method` and `action` come from the wrapped form.
 | `restoreFormState()` | Applies saved values to current fields |
 | `clearSavedData()` | Removes saved values for the current form key |
 
+Calls to `saveFormState()` save immediately. Saves triggered by `input` and
+`change` events use a short debounce to avoid serializing the complete form and
+writing to `localStorage` for every keystroke. Pending changes are flushed when
+the page is hidden.
+
 ## Field Support
 
 Supported controls include:
-- `input` (except `type="file"`, `submit`, `button`, `reset`, and `image`)
+- `input` (except `type="password"`, `file`, `submit`, `button`, `reset`, and `image`)
 - `textarea`
 - `select` (single and multiple)
 
-File fields are intentionally excluded.
+File and password fields are always excluded. Password values are neither saved
+nor restored, even if their field names appear in `retain`.
+
+## Privacy and Storage Errors
+
+Saved values are stored as plain text in `localStorage`. Any JavaScript running
+on the same origin can read them, so avoid wrapping forms that collect other
+sensitive information that should not persist on the device. The component
+automatically removes identifiable password entries written by earlier
+versions when it reads saved state.
+
+If a browser blocks `localStorage`, its quota is exhausted, or another storage
+operation fails, the component dispatches a bubbling, composed
+`form-saver-error` event. Its `detail` contains:
+
+```javascript
+{
+  operation: 'read' | 'write' | 'remove',
+  error: Error
+}
+```
+
+For example:
+
+```javascript
+document.querySelector('form-saver').addEventListener(
+  'form-saver-error',
+  ({ detail }) => {
+    console.error(`Could not ${detail.operation} saved form data`, detail.error);
+  },
+);
+```
 
 ## Browser Support
 

custom-elements.json

@@ -70,7 +70,15 @@
 							"privacy": "public"
 						}
 					],
-					"events": [],
+					"events": [
+						{
+							"name": "form-saver-error",
+							"description": "Fired when localStorage cannot be read, written, or cleared.",
+							"type": {
+								"text": "CustomEvent<{ operation: 'read' | 'write' | 'remove'; error: unknown }>"
+							}
+						}
+					],
 					"attributes": [
 						{
 							"name": "retain",

form-saver.d.ts

@@ -8,7 +8,13 @@
  * @attr {string} retain-choice-label - Label text for the injected retention checkbox.
  * @attr {string} retain-choice-container - Optional selector for a container element into which the retention checkbox is placed.
  * @attr {string} storage-key - Optional explicit storage key override.
+ * @fires form-saver-error - Fired when localStorage cannot be read, written, or cleared.
  */
+export interface FormSaverErrorDetail {
+	operation: 'read' | 'write' | 'remove';
+	error: unknown;
+}
+
 export class FormSaverElement extends HTMLElement {
 	/**
 	 * List of attributes to observe for changes.
@@ -57,7 +63,7 @@ export class FormSaverElement extends HTMLElement {
 	set storageKey(value: string | null | undefined);
 
 	/**
-	 * Saves current form state into localStorage.
+	 * Immediately saves current form state into localStorage.
 	 */
 	saveFormState(): void;
 
@@ -71,6 +77,34 @@ export class FormSaverElement extends HTMLElement {
 	 */
 	clearSavedData(): void;
 
+	addEventListener(
+		type: 'form-saver-error',
+		listener: (
+			this: FormSaverElement,
+			event: CustomEvent<FormSaverErrorDetail>,
+		) => void,
+		options?: boolean | AddEventListenerOptions,
+	): void;
+	addEventListener(
+		type: string,
+		listener: EventListenerOrEventListenerObject | null,
+		options?: boolean | AddEventListenerOptions,
+	): void;
+
+	removeEventListener(
+		type: 'form-saver-error',
+		listener: (
+			this: FormSaverElement,
+			event: CustomEvent<FormSaverErrorDetail>,
+		) => void,
+		options?: boolean | EventListenerOptions,
+	): void;
+	removeEventListener(
+		type: string,
+		listener: EventListenerOrEventListenerObject | null,
+		options?: boolean | EventListenerOptions,
+	): void;
+
 	/**
 	 * Upgrade a property to handle cases where it was set before the element upgraded.
 	 * @param prop - Property name to upgrade