npm - @veams/status-quo - Versions diffs - 1.1.0 → 1.3.0 - Mend

@veams/status-quo 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (73) hide show

package/CHANGELOG.md +53 -0
package/README.md +252 -18
package/dist/config/status-quo-config.d.ts +21 -0
package/dist/config/status-quo-config.js +48 -0
package/dist/config/status-quo-config.js.map +1 -0
package/dist/hooks/__tests__/state-selector.spec.d.ts +4 -0
package/dist/hooks/__tests__/state-selector.spec.js +384 -0
package/dist/hooks/__tests__/state-selector.spec.js.map +1 -0
package/dist/hooks/__tests__/state-singleton.spec.d.ts +4 -0
package/dist/hooks/__tests__/state-singleton.spec.js +97 -0
package/dist/hooks/__tests__/state-singleton.spec.js.map +1 -0
package/dist/hooks/index.d.ts +3 -0
package/dist/hooks/index.js +3 -0
package/dist/hooks/index.js.map +1 -1
package/dist/hooks/state-actions.d.ts +2 -0
package/dist/hooks/state-actions.js +5 -0
package/dist/hooks/state-actions.js.map +1 -0
package/dist/hooks/state-factory.d.ts +5 -0
package/dist/hooks/state-factory.js +10 -6
package/dist/hooks/state-factory.js.map +1 -1
package/dist/hooks/state-handler.d.ts +2 -0
package/dist/hooks/state-handler.js +9 -0
package/dist/hooks/state-handler.js.map +1 -0
package/dist/hooks/state-singleton.d.ts +4 -0
package/dist/hooks/state-singleton.js +3 -5
package/dist/hooks/state-singleton.js.map +1 -1
package/dist/hooks/state-subscription-selector.d.ts +5 -0
package/dist/hooks/state-subscription-selector.js +29 -0
package/dist/hooks/state-subscription-selector.js.map +1 -0
package/dist/hooks/state-subscription.d.ts +8 -1
package/dist/hooks/state-subscription.js +49 -10
package/dist/hooks/state-subscription.js.map +1 -1
package/dist/index.d.ts +7 -5
package/dist/index.js +4 -3
package/dist/index.js.map +1 -1
package/dist/store/__tests__/observable-state-handler.spec.js +68 -5
package/dist/store/__tests__/observable-state-handler.spec.js.map +1 -1
package/dist/store/__tests__/signal-state-handler.spec.js +64 -5
package/dist/store/__tests__/signal-state-handler.spec.js.map +1 -1
package/dist/store/index.d.ts +1 -1
package/dist/store/observable-state-handler.d.ts +7 -2
package/dist/store/observable-state-handler.js +17 -22
package/dist/store/observable-state-handler.js.map +1 -1
package/dist/store/signal-state-handler.d.ts +3 -1
package/dist/store/signal-state-handler.js +5 -14
package/dist/store/signal-state-handler.js.map +1 -1
package/dist/store/state-singleton.d.ts +4 -1
package/dist/store/state-singleton.js +11 -2
package/dist/store/state-singleton.js.map +1 -1
package/docs/assets/index-BBmpszOW.css +1 -0
package/docs/assets/index-Cf8El_RO.js +194 -0
package/docs/assets/statusquo-logo-8GVRbxpc.png +0 -0
package/docs/index.html +13 -0
package/package.json +1 -1
package/playground/src/App.tsx +269 -48
package/playground/src/styles.css +123 -0
package/src/config/status-quo-config.ts +76 -0
package/src/hooks/__tests__/state-selector.spec.tsx +607 -0
package/src/hooks/__tests__/state-singleton.spec.tsx +151 -0
package/src/hooks/index.ts +3 -0
package/src/hooks/state-actions.tsx +7 -0
package/src/hooks/state-factory.tsx +32 -6
package/src/hooks/state-handler.tsx +16 -0
package/src/hooks/state-singleton.tsx +17 -7
package/src/hooks/state-subscription-selector.tsx +70 -0
package/src/hooks/state-subscription.tsx +98 -21
package/src/index.ts +23 -4
package/src/store/__tests__/observable-state-handler.spec.ts +98 -11
package/src/store/__tests__/signal-state-handler.spec.ts +92 -11
package/src/store/index.ts +1 -1
package/src/store/observable-state-handler.ts +25 -27
package/src/store/signal-state-handler.ts +7 -16
package/src/store/state-singleton.ts +21 -3

package/docs/assets/statusquo-logo-8GVRbxpc.png ADDED Viewed

Binary file

package/docs/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Status Quo Playground</title>
+    <script type="module" crossorigin src="./assets/index-Cf8El_RO.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-BBmpszOW.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@veams/status-quo",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "The manager to rule states in frontend.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/playground/src/App.tsx CHANGED Viewed

@@ -1,4 +1,4 @@
-import { useEffect } from 'react';
+import { useEffect, useState } from 'react';
 import {
   makeStateSingleton,
@@ -30,7 +30,10 @@ type CounterActions = {
 class ObservableCounterStateHandler extends ObservableStateHandler<CounterState, CounterActions> {
   constructor(startCount = 0) {
-    super({ initialState: { count: startCount } });
+    super({
+      initialState: { count: startCount },
+      options: { devTools: { enabled: true, namespace: 'Counter as Observable' } },
+    });
   }
   getActions(): CounterActions {
@@ -51,7 +54,9 @@ class ObservableCounterStateHandler extends ObservableStateHandler<CounterState,
 class SignalCounterStateHandler extends SignalStateHandler<CounterState, CounterActions> {
   constructor(startCount = 0) {
-    super({ initialState: { count: startCount } });
+    super({ initialState: { count: startCount },
+      options: { devTools: { enabled: true, namespace: 'Counter as Signal' } },
+    });
   }
   getActions(): CounterActions {
@@ -159,6 +164,7 @@ function SingletonDisplay() {
 }
 export function App() {
+  const [isNavOpen, setIsNavOpen] = useState(false);
   const [observableState, observableActions] = useStateFactory(ObservableCounterFactory, [0]);
   const [signalState, signalActions] = useStateFactory(SignalCounterFactory, [0]);
@@ -222,11 +228,64 @@ const [state, actions] = useStateFactory(() => new CounterStore(), []);`;
 unsubscribe();
 store.destroy();`;
-  const singletonSnippet = `import { makeStateSingleton, useStateSingleton } from '@veams/status-quo';
+  const singletonOptionsSnippet = `import { makeStateSingleton, useStateSingleton } from '@veams/status-quo';
+const SessionSingleton = makeStateSingleton(() => new SessionStore(), {
+  // true (default): destroy when no consumers are mounted
+  // false: keep singleton instance alive across unmounts
+  destroyOnNoConsumers: false
+});
+const [state, actions] = useStateSingleton(SessionSingleton);`;
+  const apiUseStateHandlerSnippet = `const handler = useStateHandler(createUserStore, []);`;
+  const apiUseStateActionsSnippet = `const handler = useStateHandler(createUserStore, []);
+const actions = useStateActions(handler);
+actions.rename('Ada');`;
+  const apiUseStateSubscriptionSnippet = `const handler = useStateHandler(createUserStore, []);
+const [fullState] = useStateSubscription(handler);
+const [name] = useStateSubscription(handler, (state) => state.user.name);
+const [profile] = useStateSubscription(
+  handler,
+  (state) => state.user.profile,
+  (current, next) => current.id === next.id && current.role === next.role
+);`;
-const CounterSingleton = makeStateSingleton(() => new CounterStore());
+  const apiUseStateFactorySnippet = `const [state, actions] = useStateFactory(createUserStore, []);
+const [name] = useStateFactory(createUserStore, (state) => state.user.name, []);
+const [profile] = useStateFactory(
+  createUserStore,
+  (state) => state.user.profile,
+  (current, next) => current.id === next.id,
+  []
+);`;
-const [state, actions] = useStateSingleton(CounterSingleton);`;
+  const apiMakeStateSingletonSnippet = `const SessionSingleton = makeStateSingleton(() => new SessionStore(), {
+  destroyOnNoConsumers: true // default
+});
+const PersistentSessionSingleton = makeStateSingleton(() => new SessionStore(), {
+  destroyOnNoConsumers: false
+});`;
+  const apiUseStateSingletonSnippet = `const [state, actions] = useStateSingleton(SessionSingleton);
+const [userName] = useStateSingleton(SessionSingleton, (state) => state.user.name);
+// Same behavior via useStateSubscription:
+const [session] = useStateSubscription(SessionSingleton);`;
+  const apiSetupStatusQuoSnippet = `import equal from 'fast-deep-equal';
+import { setupStatusQuo } from '@veams/status-quo';
+setupStatusQuo({
+  distinct: {
+    comparator: equal
+  }
+});`;
   const composeSnippet = `import { combineLatest } from "rxjs";
@@ -278,22 +337,59 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
     Prism.highlightAll();
   }, []);
+  const closeNav = () => {
+    setIsNavOpen(false);
+  };
   return (
     <div className="app">
       <div className="brand-bar">
         <img src={statusQuoLogo} alt="StatusQuo logo" className="brand-logo" />
       </div>
       <nav className="nav">
-        <div className="nav-links">
-          <a href="#overview">Overview</a>
-          <a href="#quickstart">Quickstart</a>
-          <a href="#factory">Factory</a>
-          <a href="#demo">Demo</a>
-          <a href="#singleton">Singleton</a>
-          <a href="#singleton-demo">Singleton demo</a>
-          <a href="#compose">Compose</a>
-          <a href="#devtools">Devtools</a>
-          <a href="#cleanup">Cleanup</a>
+        <button
+          type="button"
+          className="nav-toggle"
+          aria-expanded={isNavOpen}
+          aria-controls="docs-nav-links"
+          onClick={() => setIsNavOpen((open) => !open)}
+        >
+          Sections
+        </button>
+        <div id="docs-nav-links" className={`nav-links${isNavOpen ? ' is-open' : ''}`}>
+          <a href="#overview" onClick={closeNav}>
+            Overview
+          </a>
+          <a href="#quickstart" onClick={closeNav}>
+            Quickstart
+          </a>
+          <a href="#factory" onClick={closeNav}>
+            Factory
+          </a>
+          <a href="#selectors" onClick={closeNav}>
+            Selectors
+          </a>
+          <a href="#api" onClick={closeNav}>
+            API
+          </a>
+          <a href="#demo" onClick={closeNav}>
+            Demo
+          </a>
+          <a href="#singleton" onClick={closeNav}>
+            Singleton
+          </a>
+          <a href="#singleton-demo" onClick={closeNav}>
+            Singleton demo
+          </a>
+          <a href="#compose" onClick={closeNav}>
+            Compose
+          </a>
+          <a href="#devtools" onClick={closeNav}>
+            Devtools
+          </a>
+          <a href="#cleanup" onClick={closeNav}>
+            Cleanup
+          </a>
         </div>
       </nav>
       <header id="overview" className="hero intro">
@@ -303,14 +399,13 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
           <p className="subtext">
             <span>StatusQuo</span> treats state handlers as small, composable objects with explicit
             lifecycle and a tiny interface. Components subscribe to snapshots, not
-            framework‑specific store APIs. That makes it easy to swap the engine under the
-            hood—RxJS for observable streams or Preact Signals for ultra‑light reactive state.
+            framework‑specific store APIs. That makes it easy to swap the engine under the hood—RxJS
+            for observable streams or Preact Signals for ultra‑light reactive state.
           </p>
           <p className="subtext">
-            Handlers encapsulate state transitions, expose actions, and clean up after
-            themselves. You decide whether each component should have its own instance
-            (factory) or share a singleton, while the UI stays blissfully unaware of the
-            chosen implementation.
+            Handlers encapsulate state transitions, expose actions, and clean up after themselves.
+            You decide whether each component should have its own instance (factory) or share a
+            singleton, while the UI stays blissfully unaware of the chosen implementation.
           </p>
         </div>
       </header>
@@ -321,8 +416,8 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
           <div>
             <h3>Swap the engine, keep the API</h3>
             <p>
-              Move between RxJS observables and Signals without rewriting your components.
-              Stores keep the same shape; only the internal runtime changes.
+              Move between RxJS observables and Signals without rewriting your components. Stores
+              keep the same shape; only the internal runtime changes.
             </p>
           </div>
         </article>
@@ -331,8 +426,8 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
           <div>
             <h3>Separate view and state</h3>
             <p>
-              Handlers own transitions and expose actions. Views subscribe to snapshots and
-              never touch store internals.
+              Handlers own transitions and expose actions. Views subscribe to snapshots and never
+              touch store internals.
             </p>
           </div>
         </article>
@@ -353,8 +448,8 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
           <p className="eyebrow">Quickstart</p>
           <h2>Install and wire up a handler</h2>
           <p>
-            Pick either observable or signal stores. The hooks stay the same, so you can
-            swap the backend without changing your components.
+            Pick either observable or signal stores. The hooks stay the same, so you can swap the
+            backend without changing your components.
           </p>
         </div>
         <div className="doc-snippets">
@@ -373,30 +468,148 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
             <p className="eyebrow">Factory</p>
             <h2>Fresh handler per mount</h2>
             <p>
-              Use `useStateFactory` when every component instance needs its own store. You
-              pass a factory function and dependencies, and the hook handles lifecycle
-              cleanup for you.
+              Use `useStateFactory` when each component instance needs its own store.
             </p>
+            <p className="guide-highlight">Local state, zero cross-talk, predictable lifecycles.</p>
           </div>
-          <pre className="code-block compact">
-            <code className="language-ts">{`const [state, actions] = useStateFactory(CounterFactory, [0]);`}</code>
-          </pre>
         </article>
         <article id="singleton" className="guide-card">
           <div>
             <p className="eyebrow">Singleton</p>
             <h2>One handler, many consumers</h2>
             <p>
-              Use `makeStateSingleton` and `useStateSingleton` for shared stores. Ideal for
-              global counters, user sessions, or any shared UI state.
+              Use `makeStateSingleton` + `useStateSingleton` for shared state across components.
             </p>
+            <p className="guide-highlight">One source of truth, synced everywhere.</p>
+          </div>
+        </article>
+        <article id="selectors" className="guide-card">
+          <div>
+            <p className="eyebrow">Selectors</p>
+            <h2>Avoid rerender fanout</h2>
+            <p>
+              Subscribe only to the state slice you need with selector + equality functions.
+            </p>
+            <p className="guide-highlight">Read less, rerender less, ship smoother UIs.</p>
           </div>
-          <pre className="code-block compact">
-            <code className="language-ts">{singletonSnippet}</code>
-          </pre>
         </article>
       </section>
+      <section id="api" className="doc-section">
+        <div className="doc-copy">
+          <p className="eyebrow">API</p>
+          <h2>Detailed hook and singleton reference</h2>
+        </div>
+        <div className="api-flow">
+          <div className="api-group">
+            <article className="api-composition-card">
+              <h3>Base composition</h3>
+              <p>
+                Build explicit lifecycles with `useStateHandler`, pull actions with
+                `useStateActions`, and subscribe to exact slices with `useStateSubscription`.
+              </p>
+              <p className="api-composition-punch">Maximum control, minimum magic.</p>
+            </article>
+            <div className="api-grid">
+              <article className="api-card">
+                <h3>useStateHandler(factory, params?)</h3>
+                <p>Creates one handler instance per component mount and reuses it across rerenders.</p>
+                <pre className="code-block compact">
+                  <code className="language-ts">{apiUseStateHandlerSnippet}</code>
+                </pre>
+              </article>
+              <article className="api-card">
+                <h3>useStateActions(handler)</h3>
+                <p>Returns actions without subscribing to state updates.</p>
+                <pre className="code-block compact">
+                  <code className="language-ts">{apiUseStateActionsSnippet}</code>
+                </pre>
+              </article>
+              <article className="api-card api-card-wide">
+                <h3>useStateSubscription(source, selector?, isEqual?)</h3>
+                <p>
+                  Core subscription hook. Source can be a handler or singleton. Returns
+                  `[selectedState, actions]`.
+                </p>
+                <pre className="code-block compact">
+                  <code className="language-ts">{apiUseStateSubscriptionSnippet}</code>
+                </pre>
+              </article>
+            </div>
+          </div>
+          <div className="api-group">
+            <article className="api-composition-card">
+              <h3>Shortcut composition</h3>
+              <p>
+                Reduce wiring with `useStateFactory` and `useStateSingleton` when you want
+                the same behavior in a smaller API surface.
+              </p>
+              <p className="api-composition-punch">Less wiring, same behavior.</p>
+            </article>
+            <div className="api-grid">
+              <article className="api-card">
+                <h3>useStateFactory(factory, selector?, isEqual?, params?)</h3>
+                <p>
+                  Shortcut for handler creation + subscription. Supports full state and selected
+                  slices.
+                </p>
+                <pre className="code-block compact">
+                  <code className="language-ts">{apiUseStateFactorySnippet}</code>
+                </pre>
+              </article>
+              <article className="api-card">
+                <h3>useStateSingleton(singleton, selector?, isEqual?)</h3>
+                <p>
+                  Shortcut for subscribing to a singleton. Selector and equality semantics match
+                  `useStateSubscription`.
+                </p>
+                <pre className="code-block compact">
+                  <code className="language-ts">{apiUseStateSingletonSnippet}</code>
+                </pre>
+              </article>
+            </div>
+          </div>
+          <div className="api-group">
+            <article className="api-composition-card">
+              <h3>Helper function</h3>
+              <p>
+                Configure global distinct behavior once with `setupStatusQuo` and create shared
+                singleton providers with `makeStateSingleton`.
+              </p>
+              <p className="api-composition-punch">One setup, consistent behavior.</p>
+            </article>
+            <div className="api-grid">
+              <article className="api-card">
+                <h3>setupStatusQuo(config?)</h3>
+                <p>
+                  Defines global runtime defaults for distinct update behavior. Per-handler options
+                  still override global config.
+                </p>
+                <pre className="code-block compact">
+                  <code className="language-ts">{apiSetupStatusQuoSnippet}</code>
+                </pre>
+              </article>
+              <article className="api-card">
+                <h3>makeStateSingleton(factory, options?)</h3>
+                <p>
+                  Creates a shared handler provider. `destroyOnNoConsumers` controls instance
+                  teardown.
+                </p>
+                <pre className="code-block compact">
+                  <code className="language-ts">{apiMakeStateSingletonSnippet}</code>
+                </pre>
+              </article>
+            </div>
+          </div>
+        </div>
+      </section>
       <div id="demo" className="grid">
         <CounterCard
           title="Observable State Handler"
@@ -419,10 +632,19 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
           <p className="eyebrow">Singleton demo</p>
           <h2>One store, multiple components</h2>
           <p>
-            Both panels below are subscribed to the same singleton handler. Update the
-            controller and watch the viewer react instantly.
+            Both panels below are subscribed to the same singleton handler. Update the controller
+            and watch the viewer react instantly. The handler is only disposed once the last
+            consumer unmounts (unless persistence is enabled).
+          </p>
+          <p>
+            `makeStateSingleton(factory, options)` always returns one shared instance.
+            `destroyOnNoConsumers` controls whether that instance is torn down when the last
+            `useStateSingleton` consumer unmounts.
           </p>
         </div>
+        <pre className="code-block compact">
+          <code className="language-ts">{singletonOptionsSnippet}</code>
+        </pre>
         <div className="singleton-grid">
           <SingletonControls />
           <SingletonDisplay />
@@ -435,8 +657,8 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
           <h2>Combine multiple handlers</h2>
           <p>
             Use only the slice you need. RxJS makes multi-source composition powerful and
-            declarative with operators like `combineLatest`, `switchMap`, or `debounceTime`.
-            Signals can derive values with `computed` and wire them into a parent store via
+            declarative with operators like `combineLatest`, `switchMap`, or `debounceTime`. Signals
+            can derive values with `computed` and wire them into a parent store via
             `bindSubscribable`. This keeps parent stores lean and focused.
           </p>
         </div>
@@ -450,8 +672,8 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
           <p className="eyebrow">Devtools</p>
           <h2>Redux devtools integration</h2>
           <p>
-            Enable devtools to inspect actions and state transitions. Both handlers share
-            the same options shape.
+            Enable devtools to inspect actions and state transitions. Both handlers share the same
+            options shape.
           </p>
         </div>
         <pre className="code-block">
@@ -464,15 +686,14 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
           <p className="eyebrow">Cleanup</p>
           <h2>Controlled teardown</h2>
           <p>
-            Each handler exposes `subscribe`, `getSnapshot`, and `destroy`. Use them when
-            you wire custom integrations or combine multiple stores manually.
+            Each handler exposes `subscribe`, `getSnapshot`, and `destroy`. Use them when you wire
+            custom integrations or combine multiple stores manually.
           </p>
         </div>
         <pre className="code-block">
           <code className="language-ts">{cleanupSnippet}</code>
         </pre>
       </section>
     </div>
   );
 }

package/playground/src/styles.css CHANGED Viewed

@@ -64,15 +64,32 @@ body {
   display: flex;
   align-items: center;
   justify-content: center;
+  flex-direction: column;
   padding: 10px 6px;
+  width: 100%;
+}
+.nav-toggle {
+  display: none;
+  border: 1px solid rgba(27, 27, 31, 0.18);
+  background: rgba(255, 255, 255, 0.85);
+  color: var(--ink);
+  border-radius: 999px;
+  padding: 8px 14px;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+  box-shadow: var(--shadow);
 }
 .nav-links {
   display: inline-flex;
   align-items: center;
+  justify-content: center;
   gap: 10px;
   flex-wrap: wrap;
   padding: 6px 12px;
+  width: min(100%, 980px);
   background: rgba(255, 255, 255, 0.7);
   border-radius: 999px;
   border: 1px solid rgba(27, 27, 31, 0.1);
@@ -165,6 +182,7 @@ p {
   display: grid;
   gap: 24px;
   grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  align-items: stretch;
 }
 .doc-section {
@@ -191,6 +209,7 @@ p {
   display: grid;
   gap: 20px;
   grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  align-items: stretch;
 }
 .singleton-card {
@@ -201,6 +220,8 @@ p {
   box-shadow: var(--shadow);
   display: grid;
   gap: 14px;
+  align-content: start;
+  height: 100%;
 }
 .singleton-count {
@@ -227,12 +248,75 @@ p {
   display: grid;
   gap: 20px;
   grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  align-items: stretch;
+}
+.api-flow {
+  display: grid;
+  gap: 30px;
+}
+.api-group {
+  display: grid;
+  gap: 18px;
+}
+.api-grid {
+  display: grid;
+  gap: 18px;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  align-items: stretch;
+}
+.api-composition-card {
+  padding: 2px 0 18px;
+  border-bottom: 1px solid rgba(27, 27, 31, 0.16);
+  display: grid;
+  gap: 10px;
+  align-content: start;
+}
+.api-composition-card h3 {
+  margin: 0;
+  font-size: 1rem;
+}
+.api-composition-punch {
+  margin-top: 8px;
+  font-weight: 600;
+  color: var(--ink);
+  background: linear-gradient(120deg, rgba(47, 107, 255, 0.14), rgba(255, 159, 28, 0.14));
+  border: 1px solid rgba(47, 107, 255, 0.2);
+  border-radius: var(--radius-sm);
+  padding: 10px 12px;
+}
+.api-card {
+  background: #fff;
+  border-radius: var(--radius-sm);
+  padding: 18px;
+  border: 1px solid rgba(27, 27, 31, 0.08);
+  box-shadow: var(--shadow);
+  display: grid;
+  gap: 10px;
+  align-content: start;
+  height: 100%;
+}
+.api-card h3 {
+  margin: 0;
+  font-size: 1rem;
+}
+.api-card-wide {
+  grid-column: 1 / -1;
 }
 .philosophy-grid {
   display: grid;
   gap: 20px;
   grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+  align-items: stretch;
 }
 .philosophy-card {
@@ -243,6 +327,8 @@ p {
   overflow: hidden;
   display: grid;
   gap: 16px;
+  align-content: start;
+  height: 100%;
 }
 .philosophy-card img {
@@ -266,6 +352,18 @@ p {
   box-shadow: var(--shadow);
   display: grid;
   gap: 16px;
+  align-content: start;
+  height: 100%;
+}
+.guide-highlight {
+  margin-top: 4px;
+  font-weight: 600;
+  color: var(--ink);
+  background: linear-gradient(120deg, rgba(47, 107, 255, 0.16), rgba(255, 159, 28, 0.16));
+  border: 1px solid rgba(47, 107, 255, 0.2);
+  border-radius: var(--radius-sm);
+  padding: 10px 12px;
 }
 .code-block.compact {
@@ -283,6 +381,7 @@ p {
   flex-direction: column;
   gap: 20px;
   animation: fade-up 0.6s ease both;
+  height: 100%;
 }
 .card:nth-child(2) {
@@ -392,14 +491,38 @@ p {
     padding: 0;
   }
+  .nav-toggle {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    margin-bottom: 10px;
+  }
   .nav-links {
+    display: none;
+    width: 100%;
     border-radius: var(--radius-md);
+    padding: 10px;
+    gap: 8px;
+  }
+  .nav-links.is-open {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+  .nav-links a {
+    text-align: center;
   }
   .doc-section {
     padding: 22px;
   }
+  .api-grid {
+    grid-template-columns: 1fr;
+  }
   .hero {
     padding: 26px;
   }