howone 0.2.2 → 0.2.5

package/templates/vite/.howone/skills/howone/04-app-sdk/03-auth.md

@@ -64,12 +64,14 @@ That wires:
 Pair with React:
 
 ```tsx
-<HowOneProvider auth="none" brand="visible">
+<HowOneProvider client={howone} brand="visible">
   <App />
 </HowOneProvider>
 ```
 
-`auth="none"` on the provider means **no automatic redirect**; route guards call `howone.me()` and `navigate('/login')` yourself. Keep `brand="visible"` unless the user explicitly asks to hide the bottom-right HowOne logo.
+The Provider derives its route guard from `client.auth.guard`; custom/headless clients default to no
+hosted redirect. Override `auth="none"` only when the app deliberately owns route guards. Keep
+`brand="visible"` unless the user explicitly asks to hide the bottom-right HowOne logo.
 
 | `createClient({ auth })` | Login UI | `auth.login()` | `auth.logout()` default redirect |
 |--------------------------|----------|----------------|----------------------------------|
@@ -88,7 +90,7 @@ auth: {
   mode: 'custom',
   loginPath: '/sign-in',
   logoutPath: '/sign-in', // optional; defaults to loginPath
-  guard: 'required', // optional; use with HowOneProvider auth="required" for auto-redirect to loginPath
+  guard: 'required', // optional; Provider inherits this when passed client={howone}
   getToken: async () => null, // only for headless
 }
 ```
@@ -192,6 +194,8 @@ import { createClient, defineEntities, withEntities } from '@howone/sdk'
 const client = createClient({
   projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
   env: import.meta.env.VITE_HOWONE_ENV,
+  auth: 'custom',
+  loginPath: '/login',
 })
 
 export default withEntities(client, defineEntities({ /* ... */ }))
@@ -201,9 +205,9 @@ export default withEntities(client, defineEntities({ /* ... */ }))
 
 ```tsx
 import { HowOneProvider } from '@howone/sdk/react'
-import './lib/sdk' // registers auth config
+import howone from './lib/sdk'
 
-<HowOneProvider auth="none" brand="visible">
+<HowOneProvider client={howone} brand="visible">
   <App />
 </HowOneProvider>
 ```
@@ -285,7 +289,7 @@ createClient({ projectId, env })
 ```
 
 ```tsx
-<HowOneProvider auth="required">
+<HowOneProvider client={howone}>
   <App />
 </HowOneProvider>
 ```
@@ -392,7 +396,7 @@ try {
 | Mistake | Fix |
 |---------|-----|
 | Custom `/login` page with HowOne OTP/OAuth | Add `auth: 'custom'` in `createClient` |
-| `HowOneProvider auth="required"` + custom login | Use `auth="none"`; guard with `howone.me()` |
+| Provider without `client={howone}` | Pass the composed client so auth strategy and guard are instance-consistent |
 | `howone.auth.logout()` expecting no redirect before this change | Now respects `auth: 'custom'` |
 | `auth.isAuthenticated()` on first paint | Use `await howone.me()` |
 | Phone without country code | E.164 `+86...` |

package/templates/vite/.howone/skills/howone/04-app-sdk/04-react-integration.md

@@ -1,191 +1,138 @@
 # React Integration
 
-## What `@howone/sdk/react` Provides
+Use this track for the application shell, auth context, and optional element-selector devtools.
+Read `01-client-setup.md` first and initialize `src/lib/sdk.ts` before rendering the Provider.
 
-Thin integration layer: auth context plus the HowOne floating brand button. **No** entity hooks,
-AI hooks, toast system, redirect overlay, or app-owned UI.
+## Package boundaries
 
-Exports:
-
-- `HowOneProvider`
-- `useHowoneContext`
-- `FloatingButton`
-
----
-
-## Auth: one SDK config + one Provider flag
-
-**Step 1 — `src/lib/sdk.ts` (required):**
+Keep imports on the smallest entry point:
 
 ```ts
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-})
+import { createClient } from '@howone/sdk'          // framework-neutral core
+import { HowOneProvider, useHowoneContext } from '@howone/sdk/react'
+import { ElementSelectorProvider } from '@howone/sdk/devtools' // optional editor tooling
 ```
 
-**Step 2 — Provider:**
+The core package must remain usable in workers, tests, and non-React apps. Do not import React
+components from `@howone/sdk` or selector tooling from `/react`.
+
+## Root wiring
 
 ```tsx
+import howone from '@/lib/sdk'
+import { ElementSelectorProvider } from '@howone/sdk/devtools'
 import { HowOneProvider } from '@howone/sdk/react'
-import './lib/sdk' // must import before Provider so auth config is registered
-
-<HowOneProvider auth="none" brand="visible">
-  <App />
-</HowOneProvider>
-```
-
-| Layer | Setting | Meaning |
-|-------|---------|---------|
-| `createClient` | `{ projectId, env }` (default **hosted**) | Login/logout → HowOne `/auth` |
-| `createClient` | `auth: 'custom'` | Login/logout → your `loginPath`; APIs still HowOne |
-| `HowOneProvider` | `auth="required"` | Default with hosted — redirect to HowOne login |
-| `HowOneProvider` | `auth="none"` | Use with `auth: 'custom'`; guard routes yourself |
-
-Default (HowOne hosted login):
 
-```tsx
-createClient({ projectId, env })
-<HowOneProvider auth="required" />
+export function AppRoot() {
+  return (
+    <ElementSelectorProvider>
+      <HowOneProvider client={howone} brand="visible">
+        <App />
+      </HowOneProvider>
+    </ElementSelectorProvider>
+  )
+}
 ```
 
-Custom login page (your UI, HowOne auth APIs, keep HowOne logo unless product asks to hide it):
+`ElementSelectorProvider` is optional and should be present when the app is edited through the
+HowOne iframe/editor integration. It is independent from auth. `HowOneProvider` is required when
+the app uses any HowOne runtime surface.
 
-```tsx
-createClient({ projectId, env, auth: 'custom', loginPath: '/login' })
-<HowOneProvider auth="none" brand="visible" />
-```
+The Provider waits until its auth URL/cookie check completes. With `auth="required"`, protected
+children are not briefly rendered before redirect. By default it derives the guard from
+`client.auth.guard`:
 
----
+| Client auth | Default Provider guard | Use |
+|---|---|---|
+| hosted | required | hosted login protects the app |
+| custom/headless | none | app or adapter owns login UI |
+| none | none | public app |
 
-## HowOneProvider
+Override deliberately when a single app has a public shell and protected routes:
 
 ```tsx
-<HowOneProvider
-  auth="none"
-  brand="visible"
-  onAuthRedirect={({ mode, returnUrl }) => {
-    // App may set its own loading/redirect state here.
-  }}
-  onAuthStateChange={(state) => {
-    // App may update analytics or local UI state here.
-  }}
->
+<HowOneProvider client={howone} auth="optional" brand="visible">
   <App />
 </HowOneProvider>
 ```
 
-### HowOneProviderProps
+`auth` is only a route guard. It does not change the client's login strategy. Login/logout
+destinations come from `createClient({ auth, loginPath, logoutPath })`.
 
-```ts
-type HowOneProviderAuth = 'required' | 'optional' | 'none'
+## Provider props
 
-interface HowOneProviderProps {
+```ts
+type HowOneProviderProps = {
   children: React.ReactNode
-  projectId?: string // prefer createClient projectId
-  auth?: HowOneProviderAuth
+  client?: HowOneClient
+  auth?: 'required' | 'optional' | 'none'
   brand?: 'visible' | 'hidden'
   showBrandButton?: boolean
-  theme?: 'dark' | 'light' | 'system' | 'inherit'
   onAuthStateChange?: (state: AuthState) => void
   onAuthRedirect?: (info: { mode: 'hosted' | 'custom'; returnUrl: string }) => void
 }
 ```
 
-**Important:** Provider `auth` is only a **route guard**. Login/logout URLs come from `createClient({ auth: 'custom' })`.
+`projectId` is retained only as a deprecated compatibility path when no client is passed. New app
+code must pass `client`. Theme ownership belongs to the app's ThemeProvider; the HowOne Provider
+does not accept or silently ignore theme props.
 
-The provider must not render app-owned UI. It does not own toasts, dialogs, pages, custom login UI,
-or redirect overlays. It does keep the bottom-right HowOne logo by default through `FloatingButton`.
-Use `brand="hidden"` or `showBrandButton={false}` only when the product explicitly asks to hide it.
-
----
-
-## useHowoneContext
-
-```ts
-const { user, token, isAuthenticated, logout } = useHowoneContext()
-```
-
-### Logout
+The floating HowOne brand button is visible by default. Hide it only when product requirements say
+so:
 
 ```tsx
-<button onClick={() => void logout()}>Sign out</button>
+<HowOneProvider client={howone} brand="hidden">
+  <App />
+</HowOneProvider>
 ```
 
-With `auth: 'custom'`, `logout()` clears session and navigates to `loginPath` — **not** howone.dev.
-
-Equivalent:
+The Provider does not own toasts, dialogs, loading overlays, route components, or app-specific login
+screens. Render those in the app and use SDK callbacks/results as signals.
 
-```ts
-await howone.auth.logout()
-```
-
-### Custom login page link
+## Context and logout
 
 ```tsx
-import { useNavigate } from 'react-router-dom'
-import howone from '@/lib/sdk'
-
-function Header() {
-  const navigate = useNavigate()
-  const { isAuthenticated, logout } = useHowoneContext()
+import { useHowoneContext } from '@howone/sdk/react'
 
-  if (!isAuthenticated) {
-    return <button onClick={() => navigate(howone.auth.loginPath)}>Sign in</button>
-  }
-
-  return <button onClick={() => void logout()}>Sign out</button>
+function AccountButton() {
+  const { user, isAuthenticated, logout } = useHowoneContext()
+  if (!isAuthenticated) return <a href="/login">Sign in</a>
+  return <button onClick={() => void logout()}>{user?.name || 'Sign out'}</button>
 }
 ```
 
----
+`useHowoneContext()` intentionally throws when called outside the Provider. This catches broken
+tree wiring immediately; do not add a global-token fallback.
 
-## FloatingButton
+For non-React code, use `howone.auth.*`, `howone.me()`, and `howone.requireMe()` from the singleton.
+`useAuth` remains a compatibility hook on `/react`, but `useHowoneContext` is preferred because it
+is bound to the client instance.
 
-The bottom-right HowOne logo is part of the SDK React integration and should remain visible by
-default. It does not replace your login page and does not perform app auth. Hide it only with
-`brand="hidden"` or `showBrandButton={false}`.
+## Auth state and routes
 
----
+- Hosted auth: let `HowOneProvider client={howone}` redirect.
+- Custom auth: use `auth: 'custom'`, render the app's login route, obtain OTP/OAuth tokens through
+  the SDK or adapter, and call `howone.auth.setToken(token)`.
+- Headless auth: adapter owns token refresh; an opaque token is accepted, while JWT expiration is
+  checked by the SDK.
+- Public app: use `auth: 'none'` and do not add a fake login screen.
 
-## Protected route pattern
+If a custom login page needs a route guard, use `howone.auth.isAuthenticated()` or
+`howone.me()` rather than manually parsing ownership fields.
 
-```tsx
-function ProtectedPage() {
-  const [user, setUser] = useState(null)
-  const navigate = useNavigate()
-
-  useEffect(() => {
-    howone.me()
-      .then(setUser)
-      .catch(() => navigate(howone.auth.loginPath, { replace: true }))
-  }, [navigate])
-
-  if (!user) return null
-  return <div>Welcome {user.name}</div>
-}
-```
+## Element selector security
 
----
+`ElementSelectorProvider` accepts `allowedOrigins` and `targetOrigin` for cross-window messages.
+The default trusts same-origin and the `document.referrer` origin. Use explicit origins in embedded
+multi-tenant deployments; never reintroduce `'*'` for messages carrying selected element data.
 
 ## Common mistakes
 
-| Mistake | Fix |
-|---------|-----|
-| Custom UI but no `auth: 'custom'` | Add to `createClient` |
-| `HowOneProvider auth="required"` without custom SDK auth | Hosted redirect to howone.ai |
-| `useHowoneContext` without Provider | Wrap app in `HowOneProvider` |
-| Import Provider before `./lib/sdk` | Import sdk module first |
-| Manual redirect to howone.dev on logout | Use `howone.auth.logout()` |
-| Deleting the bottom-right HowOne logo by default | Keep `brand="visible"` unless explicitly asked to hide it |
-| Expecting SDK toast APIs | Implement visible feedback in the frontend app from callbacks/results |
-
----
-
-## Import map
-
-| Need | Import |
-|------|--------|
-| Provider, context | `@howone/sdk/react` |
-| Client, OTP, OAuth | `@howone/sdk` |
-| App singleton | `@/lib/sdk` default export |
+| Mistake | Correct pattern |
+|---|---|
+| Provider without `client` | Pass the exported composed singleton. |
+| `auth="required"` on a public client | Let the client guard default to `none`, or explicitly use `auth="optional"`. |
+| Custom login plus hosted redirect | `auth: 'custom'` and Provider `auth="none"`/derived guard. |
+| Importing `ElementSelectorProvider` from `/react` | Import it from `@howone/sdk/devtools`. |
+| Calling `useHowoneContext` above the Provider | Move the component below the root Provider. |
+| Passing `theme`, `themeStorageKey`, or `forceTheme` | Configure the app's own ThemeProvider. |