react-mnemonic 1.2.1-beta1.0 → 1.4.0

package/README.md

@@ -1,3 +1,8 @@
+<p align="center">
+  <img src="./mne_logo-light.png#gh-light-mode-only" alt="react-mnemonic logo" width="220" />
+  <img src="./mne_logo.png#gh-dark-mode-only" alt="react-mnemonic logo" width="220" />
+</p>
+
 # react-mnemonic
 
 AI-friendly, persistent, type-safe state for React.
@@ -60,9 +65,52 @@ survives a full page reload.
 
 ## Pick the right entrypoint
 
-- `react-mnemonic/core` for the lean persisted-state path
-- `react-mnemonic/schema` when you want schemas, validation, and migrations
-- `react-mnemonic` if you need the backward-compatible root entrypoint
+| Entrypoint                 | Approx ESM size | Use when                                                                            |
+| -------------------------- | --------------- | ----------------------------------------------------------------------------------- |
+| `react-mnemonic/optional`  | ~4.9 KB         | You want the tiny component-library shim that falls back to local memory            |
+| `react-mnemonic/bootstrap` | ~25 KB          | You need synchronous first-paint recall before React renders                        |
+| `react-mnemonic/core`      | ~61 KB          | A provider is required and you want the lean persisted-state path                   |
+| `react-mnemonic/schema`    | ~80.5 KB        | A provider is required and you want schema validation, autoschema, and migrations   |
+| `react-mnemonic`           | ~80.5 KB        | You want the top-level full entrypoint with the same schema-capable runtime surface |
+
+These are rough current estimates from the built ESM entry files in `dist/`
+before consumer-side minification and tree-shaking. They are useful for
+relative comparison, not as a hard size guarantee.
+
+## Optional persistence for component libraries
+
+If your component may render inside or outside a `MnemonicProvider`, import the
+optional hook instead of branching at the call site.
+
+```tsx
+import { useMnemonicKeyOptional } from "react-mnemonic/optional";
+
+function SearchBox() {
+    const { value, set, remove } = useMnemonicKeyOptional("draft", {
+        defaultValue: "",
+    });
+
+    return (
+        <div>
+            <input value={value} onChange={(event) => set(event.target.value)} />
+            <button onClick={remove}>Clear</button>
+        </div>
+    );
+}
+```
+
+Inside a provider, the draft is persisted. Outside a provider, the same hook
+behaves like local in-memory state without throwing.
+
+The lean optional entrypoint exports only:
+
+- `useMnemonicKeyOptional(...)`
+- `useMnemonicOptional()`
+- `defineMnemonicKey(...)`
+
+Schema metadata such as `schema: { version }` can still be passed through the
+optional hook. Applications pay the schema/runtime cost only when they mount a
+schema-capable `MnemonicProvider`.
 
 ## AI resources
 
@@ -79,6 +127,7 @@ survives a full page reload.
 
 - [Documentation home](https://thirtytwobits.github.io/react-mnemonic/)
 - [Quick Start](https://thirtytwobits.github.io/react-mnemonic/docs/getting-started/quick-start)
+- [Optional Persistence](https://thirtytwobits.github.io/react-mnemonic/docs/guides/optional-persistence)
 - [Server Rendering](https://thirtytwobits.github.io/react-mnemonic/docs/guides/server-rendering)
 - [Canonical Key Definitions](https://thirtytwobits.github.io/react-mnemonic/docs/guides/canonical-key-definitions)
 - [Single Source of Truth Schemas](https://thirtytwobits.github.io/react-mnemonic/docs/guides/single-source-of-truth-schemas)