@guideify/react 0.1.0

package/LICENSE

@@ -0,0 +1,122 @@
+Guideify SDK License
+
+Copyright (c) 2026 Guideify. All rights reserved.
+
+This software is proprietary. It is published to the public npm registry so a
+build tool can install it, not because it is open source. The permission you
+have to use it is written below, and there is no other.
+
+
+1. Definitions
+
+   "Software" means this package and every file it publishes.
+
+   "Service" means the Guideify hosted product at https://guideify.in.
+
+   "You" means the person or organisation installing the Software, and any
+   organisation You install it on behalf of.
+
+   "Your Application" means a product You develop and operate that integrates
+   the Service.
+
+
+2. Grant
+
+   Subject to Your compliance with this license, Guideify grants You a
+   non-exclusive, worldwide, royalty-free, non-transferable, revocable license
+   to:
+
+   (a) install, copy and use the Software in order to integrate the Service
+       into Your Application;
+
+   (b) incorporate the Software into Your Application, including compiling,
+       bundling, minifying and otherwise transforming it as an ordinary build
+       step does; and
+
+   (c) distribute the Software as an incorporated part of Your Application to
+       Your users, including by serving it from Your own origin or from a
+       content delivery network You use.
+
+   Paragraph (c) is the point of the whole document. A browser SDK reaches its
+   audience only by being served from Your pages, and a proprietary license that
+   omitted it would forbid the one thing every user of this package must do.
+
+
+3. Conditions
+
+   (a) You may not distribute the Software on its own, or inside anything whose
+       purpose is to make the Software available to others. It travels inside
+       Your Application or not at all.
+
+   (b) You may not remove or alter a copyright, license or attribution notice in
+       the Software. A build step that strips comments from bundled output is
+       not a breach of this paragraph.
+
+   (c) You may not sublicense the Software except as an inseparable part of Your
+       Application, on terms no more permissive than these.
+
+
+4. Restrictions
+
+   (a) You may not modify the Software, or use it, to connect to or interoperate
+       with any service other than the Service.
+
+   (b) You may not use the Software, or knowledge gained from studying it, to
+       build a product that competes with the Service.
+
+   (c) You may not reverse engineer, decompile or disassemble the Software,
+       except where that restriction is prohibited by applicable law, or where
+       it is necessary to exercise a right applicable law grants You that cannot
+       be waived by contract.
+
+   Nothing in this section restricts what You may do with the Software's public
+   API, with its documented behaviour, or with the data the Service returns to
+   You about Your own product.
+
+
+5. Reservation of rights
+
+   All rights not expressly granted are reserved. The Software is licensed,
+   never sold, and this license transfers no ownership.
+
+
+6. Term and termination
+
+   This license takes effect when You install the Software. It ends when You
+   stop using the Service, or if You breach a term and do not remedy the breach
+   within thirty days of being told about it.
+
+   On termination You must stop distributing new copies of the Software. Copies
+   already embedded in versions of Your Application that You have already
+   distributed are unaffected, and You do not have to recall them.
+
+
+7. No warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+
+8. Limitation of liability
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL THE
+   COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+   IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+   Nothing here excludes a liability that applicable law does not permit to be
+   excluded.
+
+
+9. Relationship to the Terms of Service
+
+   The Guideify Terms of Service at https://guideify.in/terms govern the
+   Service. This license governs the Software.
+
+   It stands on its own: it is granted by the copyright holder directly, and it
+   does not depend on those terms being in force. Copyright exists without
+   incorporation, and so does a license over it.
+
+
+Questions about this license: hello@guideify.in

package/README.md

@@ -0,0 +1,79 @@
+# @guideify/react
+
+Tier 3 of the three ways to install Guideify — BUILD_REPORT §6.3. Tier 1 is a
+script tag and Tier 2 is `identify()`; this is for teams who would rather say
+both in the component tree, plus the one thing neither tier offers:
+`<GuideifyTarget>`.
+
+```bash
+npm i @guideify/react
+```
+
+```tsx
+import { GuideifyProvider, GuideifyTarget, useGuideify } from '@guideify/react';
+
+<GuideifyProvider apiKey={process.env.NEXT_PUBLIC_GUIDEIFY_KEY}>
+  <App />
+</GuideifyProvider>;
+
+// anywhere below it
+const { start, track, identify } = useGuideify();
+```
+
+## `<GuideifyTarget>`
+
+```tsx
+<GuideifyTarget id="create-project">
+  <button onClick={create}>New project</button>
+</GuideifyTarget>
+```
+
+The paved path from §3.6, as one import. `data-guideify-id` is the resolver's
+first tier: a step aimed at one never scores candidates, never lands on the
+wrong element, and never drifts when the class names around it change.
+
+It renders no element of its own — it clones the single child and adds the
+attribute — so it cannot change your layout. Given anything else (several
+children, a bare string) it renders them untouched rather than throwing.
+
+## What it does not bundle
+
+**The core is not in this package.** The provider injects the loader tag and the
+runtime arrives from the CDN, which is what keeps a canary (R-03) and the kill
+switch (R-04) able to reach you. Every import from `@guideify/js` here is
+`import type`, and `test/boundary.test.mjs` fails the build if that changes.
+
+Two consequences worth knowing:
+
+- **Already have the script tag?** Keep it. The provider never injects over an
+  existing `window.guideify`, so having both is the documented upgrade path
+  rather than a mistake — and it is why you do not get two cores.
+- **Calls before the core lands are queued, not lost.** `track()` in a mount
+  effect needs no guard. The one exception is `on()`, which owes you an
+  unsubscribe immediately; this package holds the subscription and attaches it
+  on arrival, and unsubscribing first really does mean it is never attached.
+
+## Props
+
+`GuideifyProvider` takes exactly what a script tag can carry, because the tag is
+what initialises the core:
+
+| Prop | |
+|---|---|
+| `apiKey` | required — your `pk_live_…` |
+| `cdnHost` | self-hosted or CNAME'd bundle origin |
+| `ingestHost` | analytics origin |
+| `publicKey` | turns on config signature verification |
+| `debug` | |
+| `nonce` | CSP `nonce` for the injected tag — §6.4 |
+
+`manualOnly`, `apiHost`, `dashboardOrigin` and `config` have no script-tag
+equivalent, so they are deliberately absent from the type rather than accepted
+and ignored. Use `@guideify/js` directly if you need them.
+
+Next.js App Router users: see `@guideify/next`, which reads the CSP nonce for you.
+
+## License
+
+Proprietary — see [LICENSE](./LICENSE). You may bundle this into your own
+application and serve it to your users; you may not redistribute it on its own.

package/dist/index.cjs

@@ -0,0 +1,141 @@
+'use client';
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// ../snippet/src/index.ts
+var DEFAULT_CDN = "https://cdn.guideify.in";
+function isCore(candidate) {
+  return typeof candidate?.on === "function";
+}
+function current() {
+  if (typeof window === "undefined") return void 0;
+  return window.guideify;
+}
+function coreReady() {
+  return isCore(current());
+}
+function installLoader(options) {
+  if (typeof document === "undefined") return null;
+  const existing = document.querySelector("script[data-guideify-key]");
+  if (current() || existing) return existing;
+  const cdn = options.cdnHost ?? DEFAULT_CDN;
+  const tag = document.createElement("script");
+  tag.async = true;
+  tag.src = `${cdn}/v1/loader.js`;
+  tag.setAttribute("data-guideify-key", options.apiKey);
+  if (options.cdnHost) tag.setAttribute("data-cdn", options.cdnHost);
+  if (options.ingestHost) tag.setAttribute("data-ingest", options.ingestHost);
+  if (options.publicKey) tag.setAttribute("data-public-key", options.publicKey);
+  if (options.debug) tag.setAttribute("data-debug", "");
+  if (options.nonce) tag.setAttribute("nonce", options.nonce);
+  (document.head || document.documentElement).appendChild(tag);
+  return tag;
+}
+var POLL_MS = 50;
+var LOAD_TIMEOUT_MS = 15e3;
+function whenCoreReady(tag, then) {
+  if (coreReady()) {
+    then();
+    return () => void 0;
+  }
+  let done = false;
+  const finish = () => {
+    if (done) return;
+    done = true;
+    stop();
+    then();
+  };
+  const onLoad = () => {
+    if (coreReady()) finish();
+  };
+  const started = Date.now();
+  const timer = setInterval(() => {
+    if (coreReady()) return finish();
+    if (Date.now() - started > LOAD_TIMEOUT_MS) stop();
+  }, POLL_MS);
+  function stop() {
+    clearInterval(timer);
+    tag?.removeEventListener("load", onLoad);
+  }
+  tag?.addEventListener("load", onLoad);
+  return stop;
+}
+function callCore(method, args) {
+  const target = current();
+  const fn = target?.[method];
+  if (typeof fn !== "function") return void 0;
+  try {
+    return fn.apply(target, args);
+  } catch {
+    return void 0;
+  }
+}
+var GuideifyContext = react.createContext(null);
+var pending = /* @__PURE__ */ new Set();
+function attach(event, listener) {
+  const off = callCore("on", [event, listener]);
+  return typeof off === "function" ? off : () => void 0;
+}
+function subscribe(event, listener) {
+  if (coreReady()) return attach(event, listener);
+  const intent = { event, listener, live: null, cancelled: false };
+  pending.add(intent);
+  return () => {
+    intent.cancelled = true;
+    pending.delete(intent);
+    intent.live?.();
+  };
+}
+function drainPendingSubscriptions() {
+  if (!coreReady()) return;
+  for (const intent of [...pending]) {
+    pending.delete(intent);
+    if (!intent.cancelled) intent.live = attach(intent.event, intent.listener);
+  }
+}
+function useGuideify() {
+  const context = react.useContext(GuideifyContext);
+  if (!context) {
+    throw new Error("useGuideify must be called inside a <GuideifyProvider>");
+  }
+  const { ready } = context;
+  return react.useMemo(
+    () => ({
+      start: (flowId) => void callCore("start", [flowId]),
+      stop: () => void callCore("stop", []),
+      track: (name, props) => void callCore("track", props === void 0 ? [name] : [name, props]),
+      identify: (userId, traits, opts) => void callCore("identify", [userId, traits ?? {}, opts]),
+      reset: () => void callCore("reset", []),
+      on: subscribe,
+      ready
+    }),
+    [ready]
+  );
+}
+function GuideifyProvider({ children, ...options }) {
+  const [ready, setReady] = react.useState(false);
+  const { apiKey, cdnHost, ingestHost, publicKey, debug, nonce } = options;
+  react.useEffect(() => {
+    if (!apiKey) return;
+    const tag = installLoader({ apiKey, cdnHost, ingestHost, publicKey, debug, nonce });
+    return whenCoreReady(tag, () => {
+      drainPendingSubscriptions();
+      setReady(true);
+    });
+  }, [apiKey, cdnHost, ingestHost, publicKey, debug, nonce]);
+  const value = react.useMemo(() => ({ apiKey, ready }), [apiKey, ready]);
+  return /* @__PURE__ */ jsxRuntime.jsx(GuideifyContext.Provider, { value, children });
+}
+function GuideifyTarget({ id, children }) {
+  if (!react.isValidElement(children)) return children;
+  const child = children;
+  if (child.props["data-guideify-id"] !== void 0) return child;
+  return react.cloneElement(child, { "data-guideify-id": id });
+}
+
+exports.DEFAULT_CDN = DEFAULT_CDN;
+exports.GuideifyProvider = GuideifyProvider;
+exports.GuideifyTarget = GuideifyTarget;
+exports.useGuideify = useGuideify;

package/dist/index.d.cts

@@ -0,0 +1,413 @@
+import { ReactNode } from 'react';
+
+/**
+ * The published config contract.
+ *
+ * These types are the wire format between the publisher (which compiles them
+ * into an immutable CDN artifact) and the SDK (which parses it in the end
+ * user's browser). ARCHITECTURE §14: it must be impossible for those two to
+ * drift, which is why they live in one package imported by both.
+ *
+ * Changes here are BREAKING unless purely additive with a safe default. Bump
+ * `GuideifyConfig.version` and keep the SDK tolerant of unknown fields.
+ */
+interface AncestorHint {
+    tag: string;
+    id?: string;
+    role?: string;
+    classes?: string[];
+    landmark?: string;
+}
+/**
+ * Multi-signal element identity. Deliberately records far more than is needed
+ * so the resolver can degrade gracefully as the host app changes.
+ * See BUILD_REPORT §3.2.
+ */
+interface ElementFingerprint {
+    /** Tier 1: the host app opted in with data-guideify-id. Always wins. */
+    explicitId?: string;
+    testId?: string;
+    domId?: string;
+    name?: string;
+    ariaLabel?: string;
+    role?: string;
+    tag: string;
+    cssPath?: string;
+    stableClasses?: string[];
+    ancestors?: AncestorHint[];
+    siblingIndex?: number;
+    siblingCount?: number;
+    text?: string;
+    href?: string;
+    rectRatio?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    captureViewport?: {
+        w: number;
+        h: number;
+    };
+}
+/**
+ * Content is a structured document, never an HTML string. The renderer walks
+ * this tree with createElement/textContent, which removes the injection class
+ * rather than filtering it. See BUILD_REPORT §9.3.
+ */
+type Mark = {
+    type: 'bold';
+} | {
+    type: 'italic';
+} | {
+    type: 'code';
+} | {
+    type: 'link';
+    href: string;
+};
+type ContentNode = {
+    type: 'text';
+    text: string;
+    marks?: Mark[];
+} | {
+    type: 'paragraph';
+    content?: ContentNode[];
+} | {
+    type: 'heading';
+    level?: 1 | 2 | 3;
+    content?: ContentNode[];
+} | {
+    type: 'bulletList';
+    content?: ContentNode[];
+} | {
+    type: 'orderedList';
+    content?: ContentNode[];
+} | {
+    type: 'listItem';
+    content?: ContentNode[];
+} | {
+    type: 'code';
+    text: string;
+} | {
+    type: 'image';
+    src: string;
+    alt?: string;
+} | {
+    type: 'doc';
+    content?: ContentNode[];
+};
+interface StepButton {
+    label: string;
+    action: 'next' | 'prev' | 'dismiss' | 'complete' | 'url';
+    href?: string;
+    variant?: 'primary' | 'secondary' | 'ghost';
+}
+interface StepContent {
+    title?: string;
+    body?: ContentNode;
+    media?: {
+        type: 'image';
+        src: string;
+        alt?: string;
+    };
+    buttons?: StepButton[];
+}
+type StepType = 'tooltip' | 'modal';
+type Placement = 'auto' | 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+type AdvanceOn = {
+    type: 'next_button';
+} | {
+    type: 'target_click';
+} | {
+    type: 'url_match';
+    pattern: string;
+} | {
+    type: 'event';
+    name: string;
+} | {
+    type: 'element_appears';
+    target: ElementFingerprint;
+};
+/** What to do when a step's target cannot be resolved. */
+type StepFallback = 'skip' | 'modal' | 'abort';
+interface Step {
+    id: string;
+    type: StepType;
+    /** Absent for modal steps, which are not anchored to anything. */
+    target?: ElementFingerprint;
+    content: StepContent;
+    placement?: Placement;
+    advanceOn?: AdvanceOn;
+    /** Only show once the URL matches; otherwise wait for navigation. */
+    urlPattern?: string;
+    /** Let clicks through to the highlighted element. */
+    interactive?: boolean;
+    fallback?: StepFallback;
+    /** ms to wait for the target before giving up. */
+    timeout?: number;
+    /** Extra px of breathing room around the spotlight hole. */
+    padding?: number;
+}
+type RuleOperator = 'eq' | 'neq' | 'in' | 'not_in' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'starts_with' | 'matches_regex' | 'within_last' | 'before' | 'after' | 'exists' | 'not_exists';
+interface Condition {
+    field: string;
+    operator: RuleOperator;
+    value?: unknown;
+}
+interface RuleGroup {
+    op: 'and' | 'or';
+    rules: RuleNode[];
+}
+type RuleNode = Condition | RuleGroup;
+type Trigger = {
+    type: 'auto';
+} | {
+    type: 'manual';
+} | {
+    type: 'url';
+    pattern: string;
+} | {
+    type: 'event';
+    name: string;
+} | {
+    type: 'element_appears';
+    target: ElementFingerprint;
+};
+type Frequency = 'once' | 'session' | 'until_complete' | 'always';
+interface Flow {
+    id: string;
+    name: string;
+    version: number;
+    trigger: Trigger;
+    audience?: RuleNode;
+    frequency: Frequency;
+    priority?: number;
+    /** Can the end user close this flow? Use false sparingly. */
+    dismissible?: boolean;
+    steps: Step[];
+}
+interface ThemeTokens {
+    accent?: string;
+    scrim?: string;
+    radius?: string;
+    fontFamily?: string;
+}
+interface ConfigSettings {
+    /** Max flows auto-started per session. Stops customers spamming their users. */
+    maxFlowsPerSession?: number;
+    maxFlowsPerDay?: number;
+    theme?: ThemeTokens;
+}
+interface GuideifyConfig {
+    version: number;
+    envKey: string;
+    flows: Flow[];
+    settings?: ConfigSettings;
+}
+interface UserTraits {
+    [key: string]: unknown;
+}
+interface InitOptions {
+    apiKey: string;
+    /** Origin serving the hash-addressed config blobs. */
+    cdnHost?: string;
+    /** Origin receiving batched analytics. */
+    ingestHost?: string;
+    /**
+     * Origin of the Guideify API. Reached only by design mode, to spend a nonce
+     * for a token — the end-user hot path never touches this service (§0).
+     */
+    apiHost?: string;
+    /**
+     * Origin of the Guideify dashboard, pinned on both halves of the design-mode
+     * handshake. Overridden only for self-hosted deployments and for the demo,
+     * and it is a *security* parameter: it decides which window may vouch for a
+     * nonce, so it is compiled in rather than read from the page.
+     */
+    dashboardOrigin?: string;
+    /**
+     * Base64 Ed25519 public key for this environment, from `GET /v1/envs/:id`.
+     *
+     * Supplying it turns on config verification: the pointer must be signed by the
+     * matching key and the artifact must hash to what that signature covers, or no
+     * flows run at all. It belongs in the snippet rather than in the config
+     * because the point is that it does not come from the bucket. §5.1.
+     */
+    publicKey?: string;
+    /** Bypass the network entirely and run against a literal config (tests, demos). */
+    config?: GuideifyConfig;
+    debug?: boolean;
+    /** Disable automatic flow evaluation; only `start()` will run anything. */
+    manualOnly?: boolean;
+}
+interface IdentifyOptions {
+    /** HMAC of the user id, proving the host's backend vouches for it. §9.2 */
+    userHash?: string;
+}
+
+/**
+ * @guideify/snippet — how the core gets onto the page, for every framework
+ * wrapper that has to do it. F-06.
+ *
+ * Extracted rather than copied into each wrapper, on D-259's precedent: two
+ * packages owning two copies of one contract is how the two come to disagree
+ * about it, and everything here is a contract with something else. The attribute
+ * names are the loader's, the default origin is the loader's, and the readiness
+ * test is a fact about the core. None of it is framework-shaped, which is why
+ * there is nothing to specialise per wrapper.
+ *
+ * Private and source-only, like `@guideify/shared`: consumers inline it, because
+ * a bare `@guideify/snippet` import left in a published `dist` is one an npm
+ * consumer could never resolve.
+ *
+ * **The wrapper injects the loader; it does not bundle the core.** npm-installing
+ * `@guideify/js` beside this package would be one line shorter and would pin every
+ * customer to whatever core they built against. Two release-readiness items
+ * depend on that not being true: R-03 canaries 1% of environments onto a new core
+ * hash, and R-04 is a kill switch that pins a per-environment version in Workers
+ * KV and expects it live within 60 seconds. Neither reaches a copy sitting in
+ * somebody's webpack output. The loader exists precisely so the core is
+ * "versioned separately so we can ship SDK updates without customers touching
+ * this line ever again", and a framework wrapper is not a reason to give that up.
+ *
+ * So every import from `@guideify/js` in this package is `import type`, and
+ * `test/boundary.test.mjs` is what keeps it that way.
+ */
+/**
+ * The subset of `InitOptions` the pasted snippet can actually carry.
+ *
+ * Deliberately not all of it. `standalone.ts` auto-initialises from the script
+ * tag's data attributes, and these five are the ones it reads — so these are the
+ * five a tag can express. `manualOnly`, `apiHost`, `dashboardOrigin` and `config`
+ * have no attribute and are not silently dropped here: they are absent from the
+ * type, so asking for one is a compile error rather than a setting that appears
+ * to be applied and is not.
+ */
+interface SnippetOptions extends Pick<InitOptions, 'apiKey'> {
+    cdnHost?: string | undefined;
+    ingestHost?: string | undefined;
+    publicKey?: string | undefined;
+    debug?: boolean | undefined;
+    /**
+     * CSP `nonce` for the injected tag — BUILD_REPORT §6.4.
+     *
+     * A page served with `script-src 'nonce-…'` refuses an injected script that
+     * does not carry it, and the failure is silent from the host app's point of
+     * view: no tours, no error anybody connects to us.
+     */
+    nonce?: string | undefined;
+}
+/** Where the loader lives when nothing says otherwise. Mirrors `loader.ts`. */
+declare const DEFAULT_CDN = "https://cdn.guideify.in";
+
+interface GuideifyProviderProps extends SnippetOptions {
+    children: ReactNode;
+}
+/**
+ * Mounts Guideify for a React tree — BUILD_REPORT §6.3.
+ *
+ * ```tsx
+ * <GuideifyProvider apiKey={process.env.NEXT_PUBLIC_GUIDEIFY_KEY}>
+ *   <App />
+ * </GuideifyProvider>
+ * ```
+ *
+ * **Nothing touches `window` during render**, which is the Next.js App Router
+ * pitfall §6.4 names: the tag goes in from an effect, so a server render
+ * produces the same markup as the client's first pass and nothing hydrates
+ * mismatched.
+ *
+ * **This does not call `init`.** The loader's tag carries `data-guideify-key` and
+ * `standalone.ts` initialises from it on arrival, so a provider that also called
+ * `init` would be the second call and the core would warn and ignore it. The
+ * props are therefore exactly what a tag can express (`SnippetOptions`) rather
+ * than all of `InitOptions`.
+ *
+ * Mounted twice, the second one adds nothing: `installLoader` refuses to inject
+ * over an existing `window.guideify`, so a nested provider is a no-op rather than
+ * a second core.
+ */
+declare function GuideifyProvider({ children, ...options }: GuideifyProviderProps): ReactNode;
+
+interface GuideifyTargetProps {
+    /** The stable name a flow step aims at. Yours to choose; never changes. */
+    id: string;
+    children: ReactNode;
+}
+/**
+ * The paved path from BUILD_REPORT §3.6, as one import.
+ *
+ * ```tsx
+ * <GuideifyTarget id="create-project">
+ *   <button onClick={create}>New project</button>
+ * </GuideifyTarget>
+ * ```
+ *
+ * An element marked this way resolves exactly and for free: `data-guideify-id` is
+ * the resolver's first tier, so it never scores candidates, never lands on the
+ * wrong one, and never drifts when the class names around it change. §3.6's
+ * finding is that the customers who do this do not churn over broken tours —
+ * which makes the cost of doing it the thing worth attacking, and one import
+ * beats a code review about a magic attribute.
+ *
+ * **Renders no element of its own.** It clones the single child and adds the
+ * attribute, because a wrapper `<div>` would change the host app's layout to
+ * suit our targeting — exactly the "zero impact on host app" §6.5 promises. The
+ * cost is the constraint: one child, and it has to be an element that puts its
+ * props on a DOM node.
+ *
+ * Given anything else — several children, a bare string, a fragment — it renders
+ * them untouched rather than throwing. A missing attribute costs a step its
+ * exact match and the resolver falls back to fingerprinting; an exception costs
+ * the customer their page.
+ */
+declare function GuideifyTarget({ id, children }: GuideifyTargetProps): ReactNode;
+
+/**
+ * The four public events the core emits. `PublicEvent` is module-private in
+ * `core/guideify.ts`, so it is restated rather than imported — and
+ * `test/surface.test.mjs` reads that file to prove the two lists still agree.
+ */
+type GuideifyEvent = 'flow_started' | 'flow_completed' | 'flow_dismissed' | 'step_viewed';
+type Unsubscribe = () => void;
+interface GuideifyApi {
+    /** Starts one flow by id, regardless of its trigger or frequency rules. */
+    start(flowId: string): void;
+    /** Ends whatever is running. Safe when nothing is. */
+    stop(): void;
+    track(name: string, props?: Record<string, unknown>): void;
+    identify(userId: string, traits?: UserTraits, opts?: IdentifyOptions): void;
+    /** Forgets this browser's identity and progress — call it on sign-out. */
+    reset(): void;
+    /**
+     * Subscribes to a flow lifecycle event.
+     *
+     * The one method that cannot be queued: the loader's stub hands back nothing,
+     * and `on` owes its caller an unsubscribe immediately. So before the core
+     * arrives this registers the intent and returns a canceller that honours it —
+     * unsubscribing between mount and arrival really does mean the listener is
+     * never attached.
+     */
+    on(event: GuideifyEvent, listener: (payload: unknown) => void): Unsubscribe;
+    /** Whether the core has arrived. Calls made before it do not need this. */
+    ready: boolean;
+}
+/**
+ * The hook — BUILD_REPORT §6.3.
+ *
+ * ```tsx
+ * const { start, track, identify } = useGuideify();
+ * ```
+ *
+ * **Every method is safe to call before the core arrives.** The loader installs
+ * a queue for exactly this, so `track()` in a mount effect is not a race the
+ * caller has to think about — which is most of what this package is for.
+ *
+ * Throws when there is no provider above it, and that is the one thing here that
+ * does throw: it is a mistake in the component tree, it is the same on every
+ * render, and the alternative is a hook that silently does nothing for the life
+ * of the application.
+ */
+declare function useGuideify(): GuideifyApi;
+
+export { DEFAULT_CDN, type GuideifyApi, type GuideifyEvent, GuideifyProvider, type GuideifyProviderProps, GuideifyTarget, type GuideifyTargetProps, type SnippetOptions, type Unsubscribe, useGuideify };

package/dist/index.d.ts

@@ -0,0 +1,413 @@
+import { ReactNode } from 'react';
+
+/**
+ * The published config contract.
+ *
+ * These types are the wire format between the publisher (which compiles them
+ * into an immutable CDN artifact) and the SDK (which parses it in the end
+ * user's browser). ARCHITECTURE §14: it must be impossible for those two to
+ * drift, which is why they live in one package imported by both.
+ *
+ * Changes here are BREAKING unless purely additive with a safe default. Bump
+ * `GuideifyConfig.version` and keep the SDK tolerant of unknown fields.
+ */
+interface AncestorHint {
+    tag: string;
+    id?: string;
+    role?: string;
+    classes?: string[];
+    landmark?: string;
+}
+/**
+ * Multi-signal element identity. Deliberately records far more than is needed
+ * so the resolver can degrade gracefully as the host app changes.
+ * See BUILD_REPORT §3.2.
+ */
+interface ElementFingerprint {
+    /** Tier 1: the host app opted in with data-guideify-id. Always wins. */
+    explicitId?: string;
+    testId?: string;
+    domId?: string;
+    name?: string;
+    ariaLabel?: string;
+    role?: string;
+    tag: string;
+    cssPath?: string;
+    stableClasses?: string[];
+    ancestors?: AncestorHint[];
+    siblingIndex?: number;
+    siblingCount?: number;
+    text?: string;
+    href?: string;
+    rectRatio?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    captureViewport?: {
+        w: number;
+        h: number;
+    };
+}
+/**
+ * Content is a structured document, never an HTML string. The renderer walks
+ * this tree with createElement/textContent, which removes the injection class
+ * rather than filtering it. See BUILD_REPORT §9.3.
+ */
+type Mark = {
+    type: 'bold';
+} | {
+    type: 'italic';
+} | {
+    type: 'code';
+} | {
+    type: 'link';
+    href: string;
+};
+type ContentNode = {
+    type: 'text';
+    text: string;
+    marks?: Mark[];
+} | {
+    type: 'paragraph';
+    content?: ContentNode[];
+} | {
+    type: 'heading';
+    level?: 1 | 2 | 3;
+    content?: ContentNode[];
+} | {
+    type: 'bulletList';
+    content?: ContentNode[];
+} | {
+    type: 'orderedList';
+    content?: ContentNode[];
+} | {
+    type: 'listItem';
+    content?: ContentNode[];
+} | {
+    type: 'code';
+    text: string;
+} | {
+    type: 'image';
+    src: string;
+    alt?: string;
+} | {
+    type: 'doc';
+    content?: ContentNode[];
+};
+interface StepButton {
+    label: string;
+    action: 'next' | 'prev' | 'dismiss' | 'complete' | 'url';
+    href?: string;
+    variant?: 'primary' | 'secondary' | 'ghost';
+}
+interface StepContent {
+    title?: string;
+    body?: ContentNode;
+    media?: {
+        type: 'image';
+        src: string;
+        alt?: string;
+    };
+    buttons?: StepButton[];
+}
+type StepType = 'tooltip' | 'modal';
+type Placement = 'auto' | 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+type AdvanceOn = {
+    type: 'next_button';
+} | {
+    type: 'target_click';
+} | {
+    type: 'url_match';
+    pattern: string;
+} | {
+    type: 'event';
+    name: string;
+} | {
+    type: 'element_appears';
+    target: ElementFingerprint;
+};
+/** What to do when a step's target cannot be resolved. */
+type StepFallback = 'skip' | 'modal' | 'abort';
+interface Step {
+    id: string;
+    type: StepType;
+    /** Absent for modal steps, which are not anchored to anything. */
+    target?: ElementFingerprint;
+    content: StepContent;
+    placement?: Placement;
+    advanceOn?: AdvanceOn;
+    /** Only show once the URL matches; otherwise wait for navigation. */
+    urlPattern?: string;
+    /** Let clicks through to the highlighted element. */
+    interactive?: boolean;
+    fallback?: StepFallback;
+    /** ms to wait for the target before giving up. */
+    timeout?: number;
+    /** Extra px of breathing room around the spotlight hole. */
+    padding?: number;
+}
+type RuleOperator = 'eq' | 'neq' | 'in' | 'not_in' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'starts_with' | 'matches_regex' | 'within_last' | 'before' | 'after' | 'exists' | 'not_exists';
+interface Condition {
+    field: string;
+    operator: RuleOperator;
+    value?: unknown;
+}
+interface RuleGroup {
+    op: 'and' | 'or';
+    rules: RuleNode[];
+}
+type RuleNode = Condition | RuleGroup;
+type Trigger = {
+    type: 'auto';
+} | {
+    type: 'manual';
+} | {
+    type: 'url';
+    pattern: string;
+} | {
+    type: 'event';
+    name: string;
+} | {
+    type: 'element_appears';
+    target: ElementFingerprint;
+};
+type Frequency = 'once' | 'session' | 'until_complete' | 'always';
+interface Flow {
+    id: string;
+    name: string;
+    version: number;
+    trigger: Trigger;
+    audience?: RuleNode;
+    frequency: Frequency;
+    priority?: number;
+    /** Can the end user close this flow? Use false sparingly. */
+    dismissible?: boolean;
+    steps: Step[];
+}
+interface ThemeTokens {
+    accent?: string;
+    scrim?: string;
+    radius?: string;
+    fontFamily?: string;
+}
+interface ConfigSettings {
+    /** Max flows auto-started per session. Stops customers spamming their users. */
+    maxFlowsPerSession?: number;
+    maxFlowsPerDay?: number;
+    theme?: ThemeTokens;
+}
+interface GuideifyConfig {
+    version: number;
+    envKey: string;
+    flows: Flow[];
+    settings?: ConfigSettings;
+}
+interface UserTraits {
+    [key: string]: unknown;
+}
+interface InitOptions {
+    apiKey: string;
+    /** Origin serving the hash-addressed config blobs. */
+    cdnHost?: string;
+    /** Origin receiving batched analytics. */
+    ingestHost?: string;
+    /**
+     * Origin of the Guideify API. Reached only by design mode, to spend a nonce
+     * for a token — the end-user hot path never touches this service (§0).
+     */
+    apiHost?: string;
+    /**
+     * Origin of the Guideify dashboard, pinned on both halves of the design-mode
+     * handshake. Overridden only for self-hosted deployments and for the demo,
+     * and it is a *security* parameter: it decides which window may vouch for a
+     * nonce, so it is compiled in rather than read from the page.
+     */
+    dashboardOrigin?: string;
+    /**
+     * Base64 Ed25519 public key for this environment, from `GET /v1/envs/:id`.
+     *
+     * Supplying it turns on config verification: the pointer must be signed by the
+     * matching key and the artifact must hash to what that signature covers, or no
+     * flows run at all. It belongs in the snippet rather than in the config
+     * because the point is that it does not come from the bucket. §5.1.
+     */
+    publicKey?: string;
+    /** Bypass the network entirely and run against a literal config (tests, demos). */
+    config?: GuideifyConfig;
+    debug?: boolean;
+    /** Disable automatic flow evaluation; only `start()` will run anything. */
+    manualOnly?: boolean;
+}
+interface IdentifyOptions {
+    /** HMAC of the user id, proving the host's backend vouches for it. §9.2 */
+    userHash?: string;
+}
+
+/**
+ * @guideify/snippet — how the core gets onto the page, for every framework
+ * wrapper that has to do it. F-06.
+ *
+ * Extracted rather than copied into each wrapper, on D-259's precedent: two
+ * packages owning two copies of one contract is how the two come to disagree
+ * about it, and everything here is a contract with something else. The attribute
+ * names are the loader's, the default origin is the loader's, and the readiness
+ * test is a fact about the core. None of it is framework-shaped, which is why
+ * there is nothing to specialise per wrapper.
+ *
+ * Private and source-only, like `@guideify/shared`: consumers inline it, because
+ * a bare `@guideify/snippet` import left in a published `dist` is one an npm
+ * consumer could never resolve.
+ *
+ * **The wrapper injects the loader; it does not bundle the core.** npm-installing
+ * `@guideify/js` beside this package would be one line shorter and would pin every
+ * customer to whatever core they built against. Two release-readiness items
+ * depend on that not being true: R-03 canaries 1% of environments onto a new core
+ * hash, and R-04 is a kill switch that pins a per-environment version in Workers
+ * KV and expects it live within 60 seconds. Neither reaches a copy sitting in
+ * somebody's webpack output. The loader exists precisely so the core is
+ * "versioned separately so we can ship SDK updates without customers touching
+ * this line ever again", and a framework wrapper is not a reason to give that up.
+ *
+ * So every import from `@guideify/js` in this package is `import type`, and
+ * `test/boundary.test.mjs` is what keeps it that way.
+ */
+/**
+ * The subset of `InitOptions` the pasted snippet can actually carry.
+ *
+ * Deliberately not all of it. `standalone.ts` auto-initialises from the script
+ * tag's data attributes, and these five are the ones it reads — so these are the
+ * five a tag can express. `manualOnly`, `apiHost`, `dashboardOrigin` and `config`
+ * have no attribute and are not silently dropped here: they are absent from the
+ * type, so asking for one is a compile error rather than a setting that appears
+ * to be applied and is not.
+ */
+interface SnippetOptions extends Pick<InitOptions, 'apiKey'> {
+    cdnHost?: string | undefined;
+    ingestHost?: string | undefined;
+    publicKey?: string | undefined;
+    debug?: boolean | undefined;
+    /**
+     * CSP `nonce` for the injected tag — BUILD_REPORT §6.4.
+     *
+     * A page served with `script-src 'nonce-…'` refuses an injected script that
+     * does not carry it, and the failure is silent from the host app's point of
+     * view: no tours, no error anybody connects to us.
+     */
+    nonce?: string | undefined;
+}
+/** Where the loader lives when nothing says otherwise. Mirrors `loader.ts`. */
+declare const DEFAULT_CDN = "https://cdn.guideify.in";
+
+interface GuideifyProviderProps extends SnippetOptions {
+    children: ReactNode;
+}
+/**
+ * Mounts Guideify for a React tree — BUILD_REPORT §6.3.
+ *
+ * ```tsx
+ * <GuideifyProvider apiKey={process.env.NEXT_PUBLIC_GUIDEIFY_KEY}>
+ *   <App />
+ * </GuideifyProvider>
+ * ```
+ *
+ * **Nothing touches `window` during render**, which is the Next.js App Router
+ * pitfall §6.4 names: the tag goes in from an effect, so a server render
+ * produces the same markup as the client's first pass and nothing hydrates
+ * mismatched.
+ *
+ * **This does not call `init`.** The loader's tag carries `data-guideify-key` and
+ * `standalone.ts` initialises from it on arrival, so a provider that also called
+ * `init` would be the second call and the core would warn and ignore it. The
+ * props are therefore exactly what a tag can express (`SnippetOptions`) rather
+ * than all of `InitOptions`.
+ *
+ * Mounted twice, the second one adds nothing: `installLoader` refuses to inject
+ * over an existing `window.guideify`, so a nested provider is a no-op rather than
+ * a second core.
+ */
+declare function GuideifyProvider({ children, ...options }: GuideifyProviderProps): ReactNode;
+
+interface GuideifyTargetProps {
+    /** The stable name a flow step aims at. Yours to choose; never changes. */
+    id: string;
+    children: ReactNode;
+}
+/**
+ * The paved path from BUILD_REPORT §3.6, as one import.
+ *
+ * ```tsx
+ * <GuideifyTarget id="create-project">
+ *   <button onClick={create}>New project</button>
+ * </GuideifyTarget>
+ * ```
+ *
+ * An element marked this way resolves exactly and for free: `data-guideify-id` is
+ * the resolver's first tier, so it never scores candidates, never lands on the
+ * wrong one, and never drifts when the class names around it change. §3.6's
+ * finding is that the customers who do this do not churn over broken tours —
+ * which makes the cost of doing it the thing worth attacking, and one import
+ * beats a code review about a magic attribute.
+ *
+ * **Renders no element of its own.** It clones the single child and adds the
+ * attribute, because a wrapper `<div>` would change the host app's layout to
+ * suit our targeting — exactly the "zero impact on host app" §6.5 promises. The
+ * cost is the constraint: one child, and it has to be an element that puts its
+ * props on a DOM node.
+ *
+ * Given anything else — several children, a bare string, a fragment — it renders
+ * them untouched rather than throwing. A missing attribute costs a step its
+ * exact match and the resolver falls back to fingerprinting; an exception costs
+ * the customer their page.
+ */
+declare function GuideifyTarget({ id, children }: GuideifyTargetProps): ReactNode;
+
+/**
+ * The four public events the core emits. `PublicEvent` is module-private in
+ * `core/guideify.ts`, so it is restated rather than imported — and
+ * `test/surface.test.mjs` reads that file to prove the two lists still agree.
+ */
+type GuideifyEvent = 'flow_started' | 'flow_completed' | 'flow_dismissed' | 'step_viewed';
+type Unsubscribe = () => void;
+interface GuideifyApi {
+    /** Starts one flow by id, regardless of its trigger or frequency rules. */
+    start(flowId: string): void;
+    /** Ends whatever is running. Safe when nothing is. */
+    stop(): void;
+    track(name: string, props?: Record<string, unknown>): void;
+    identify(userId: string, traits?: UserTraits, opts?: IdentifyOptions): void;
+    /** Forgets this browser's identity and progress — call it on sign-out. */
+    reset(): void;
+    /**
+     * Subscribes to a flow lifecycle event.
+     *
+     * The one method that cannot be queued: the loader's stub hands back nothing,
+     * and `on` owes its caller an unsubscribe immediately. So before the core
+     * arrives this registers the intent and returns a canceller that honours it —
+     * unsubscribing between mount and arrival really does mean the listener is
+     * never attached.
+     */
+    on(event: GuideifyEvent, listener: (payload: unknown) => void): Unsubscribe;
+    /** Whether the core has arrived. Calls made before it do not need this. */
+    ready: boolean;
+}
+/**
+ * The hook — BUILD_REPORT §6.3.
+ *
+ * ```tsx
+ * const { start, track, identify } = useGuideify();
+ * ```
+ *
+ * **Every method is safe to call before the core arrives.** The loader installs
+ * a queue for exactly this, so `track()` in a mount effect is not a race the
+ * caller has to think about — which is most of what this package is for.
+ *
+ * Throws when there is no provider above it, and that is the one thing here that
+ * does throw: it is a mistake in the component tree, it is the same on every
+ * render, and the alternative is a hook that silently does nothing for the life
+ * of the application.
+ */
+declare function useGuideify(): GuideifyApi;
+
+export { DEFAULT_CDN, type GuideifyApi, type GuideifyEvent, GuideifyProvider, type GuideifyProviderProps, GuideifyTarget, type GuideifyTargetProps, type SnippetOptions, type Unsubscribe, useGuideify };

package/dist/index.js

@@ -0,0 +1,136 @@
+'use client';
+import { createContext, useContext, useMemo, useState, useEffect, isValidElement, cloneElement } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// ../snippet/src/index.ts
+var DEFAULT_CDN = "https://cdn.guideify.in";
+function isCore(candidate) {
+  return typeof candidate?.on === "function";
+}
+function current() {
+  if (typeof window === "undefined") return void 0;
+  return window.guideify;
+}
+function coreReady() {
+  return isCore(current());
+}
+function installLoader(options) {
+  if (typeof document === "undefined") return null;
+  const existing = document.querySelector("script[data-guideify-key]");
+  if (current() || existing) return existing;
+  const cdn = options.cdnHost ?? DEFAULT_CDN;
+  const tag = document.createElement("script");
+  tag.async = true;
+  tag.src = `${cdn}/v1/loader.js`;
+  tag.setAttribute("data-guideify-key", options.apiKey);
+  if (options.cdnHost) tag.setAttribute("data-cdn", options.cdnHost);
+  if (options.ingestHost) tag.setAttribute("data-ingest", options.ingestHost);
+  if (options.publicKey) tag.setAttribute("data-public-key", options.publicKey);
+  if (options.debug) tag.setAttribute("data-debug", "");
+  if (options.nonce) tag.setAttribute("nonce", options.nonce);
+  (document.head || document.documentElement).appendChild(tag);
+  return tag;
+}
+var POLL_MS = 50;
+var LOAD_TIMEOUT_MS = 15e3;
+function whenCoreReady(tag, then) {
+  if (coreReady()) {
+    then();
+    return () => void 0;
+  }
+  let done = false;
+  const finish = () => {
+    if (done) return;
+    done = true;
+    stop();
+    then();
+  };
+  const onLoad = () => {
+    if (coreReady()) finish();
+  };
+  const started = Date.now();
+  const timer = setInterval(() => {
+    if (coreReady()) return finish();
+    if (Date.now() - started > LOAD_TIMEOUT_MS) stop();
+  }, POLL_MS);
+  function stop() {
+    clearInterval(timer);
+    tag?.removeEventListener("load", onLoad);
+  }
+  tag?.addEventListener("load", onLoad);
+  return stop;
+}
+function callCore(method, args) {
+  const target = current();
+  const fn = target?.[method];
+  if (typeof fn !== "function") return void 0;
+  try {
+    return fn.apply(target, args);
+  } catch {
+    return void 0;
+  }
+}
+var GuideifyContext = createContext(null);
+var pending = /* @__PURE__ */ new Set();
+function attach(event, listener) {
+  const off = callCore("on", [event, listener]);
+  return typeof off === "function" ? off : () => void 0;
+}
+function subscribe(event, listener) {
+  if (coreReady()) return attach(event, listener);
+  const intent = { event, listener, live: null, cancelled: false };
+  pending.add(intent);
+  return () => {
+    intent.cancelled = true;
+    pending.delete(intent);
+    intent.live?.();
+  };
+}
+function drainPendingSubscriptions() {
+  if (!coreReady()) return;
+  for (const intent of [...pending]) {
+    pending.delete(intent);
+    if (!intent.cancelled) intent.live = attach(intent.event, intent.listener);
+  }
+}
+function useGuideify() {
+  const context = useContext(GuideifyContext);
+  if (!context) {
+    throw new Error("useGuideify must be called inside a <GuideifyProvider>");
+  }
+  const { ready } = context;
+  return useMemo(
+    () => ({
+      start: (flowId) => void callCore("start", [flowId]),
+      stop: () => void callCore("stop", []),
+      track: (name, props) => void callCore("track", props === void 0 ? [name] : [name, props]),
+      identify: (userId, traits, opts) => void callCore("identify", [userId, traits ?? {}, opts]),
+      reset: () => void callCore("reset", []),
+      on: subscribe,
+      ready
+    }),
+    [ready]
+  );
+}
+function GuideifyProvider({ children, ...options }) {
+  const [ready, setReady] = useState(false);
+  const { apiKey, cdnHost, ingestHost, publicKey, debug, nonce } = options;
+  useEffect(() => {
+    if (!apiKey) return;
+    const tag = installLoader({ apiKey, cdnHost, ingestHost, publicKey, debug, nonce });
+    return whenCoreReady(tag, () => {
+      drainPendingSubscriptions();
+      setReady(true);
+    });
+  }, [apiKey, cdnHost, ingestHost, publicKey, debug, nonce]);
+  const value = useMemo(() => ({ apiKey, ready }), [apiKey, ready]);
+  return /* @__PURE__ */ jsx(GuideifyContext.Provider, { value, children });
+}
+function GuideifyTarget({ id, children }) {
+  if (!isValidElement(children)) return children;
+  const child = children;
+  if (child.props["data-guideify-id"] !== void 0) return child;
+  return cloneElement(child, { "data-guideify-id": id });
+}
+
+export { DEFAULT_CDN, GuideifyProvider, GuideifyTarget, useGuideify };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@guideify/react",
+  "version": "0.1.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"test/*.test.mjs\"",
+    "verify": "npm run typecheck && npm run build && npm run test",
+    "verify:package": "node ../../scripts/verify-package.mjs react",
+    "prepublishOnly": "npm run verify && npm run verify:package"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@guideify/js": "*",
+    "@guideify/snippet": "*",
+    "@types/react": "^19.2.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vikasOzark/guidely.git",
+    "directory": "packages/react"
+  }
+}