@connextar/house 0.4.0 → 0.5.0

package/dist/setup-guide/class-names.js

@@ -0,0 +1,63 @@
+export const SETUP_GUIDE_CLASS_NAMES = {
+    card: "overflow-hidden rounded-2xl border border-border bg-card shadow-sm",
+    band: "flex flex-col p-6 text-white sm:p-8",
+    bandEyebrow: "text-xs font-bold tracking-[0.14em] text-emerald-300 uppercase",
+    bandTitle: "mt-3.5 text-2xl leading-tight font-bold tracking-tight text-balance",
+    bandLead: "mt-3 text-sm leading-relaxed text-slate-300",
+    bandMuted: "text-slate-400",
+    bandLink: "font-medium text-emerald-300 underline-offset-4 hover:underline",
+    bandQuietButton: "text-slate-400 hover:text-white focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none",
+    panel: "min-w-0 flex-1 p-3 sm:p-5",
+    panelHeading: "text-sm font-semibold",
+    panelNote: "text-xs text-muted-foreground",
+    row: "grid grid-cols-[auto_minmax(0,1fr)] gap-x-3.5 gap-y-2 border-b border-border px-3 py-3.5 last:border-b-0 sm:px-4",
+    rowNext: "my-1 rounded-xl border border-primary/25 bg-primary/5 px-3 py-4 sm:px-4",
+    rowTitle: "text-[15px] font-semibold",
+    rowTitleDone: "text-muted-foreground",
+    rowDescription: "mt-1 max-w-xl text-[13px] leading-normal text-muted-foreground",
+    subRow: "flex flex-wrap items-center gap-x-3 gap-y-1 border-t border-border py-2.5",
+    circle: "flex shrink-0 items-center justify-center rounded-full text-xs font-semibold tabular-nums",
+    circleDone: "bg-primary text-primary-foreground",
+    circleNext: "bg-primary text-primary-foreground ring-4 ring-primary/15",
+    circleReady: "border-[1.5px] border-primary bg-background text-primary",
+    circleTodo: "border-[1.5px] border-muted-foreground/40 bg-background text-muted-foreground",
+    chip: "inline-flex h-6 shrink-0 items-center gap-1 rounded-full border border-primary/30 bg-primary/10 px-2 text-xs font-semibold whitespace-nowrap tabular-nums text-primary",
+    chipEarned: "inline-flex h-6 shrink-0 items-center gap-1 px-0.5 text-xs font-semibold whitespace-nowrap tabular-nums text-primary",
+    chipOnComplete: "border-dashed border-primary/50 bg-background",
+    chipDark: "border-white/35 bg-white/10 text-white",
+    bar: "h-2 w-full overflow-hidden rounded-full bg-secondary",
+    barFill: "h-full rounded-full bg-primary transition-[width]",
+    segment: "h-1.5 flex-1 rounded-full",
+    segmentDone: "bg-primary",
+    segmentDoneDark: "bg-emerald-300",
+    segmentTodo: "bg-secondary",
+    segmentTodoDark: "bg-white/15",
+    button: "inline-flex items-center gap-1.5 rounded-md px-3 py-2 text-sm font-medium transition-colors focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none disabled:pointer-events-none disabled:opacity-60",
+    buttonPrimary: "bg-primary text-primary-foreground hover:bg-primary/90",
+    buttonOutline: "border border-border hover:bg-muted",
+    buttonQuiet: "text-muted-foreground hover:bg-muted hover:text-foreground",
+    iconButton: "inline-flex size-8 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none",
+    popover: "absolute right-0 z-50 mt-1 w-80 rounded-lg border border-border bg-popover p-4 text-popover-foreground shadow-lg",
+    popoverTitle: "text-sm font-semibold",
+    popoverStep: "flex gap-2.5 text-[13px] leading-normal",
+    popoverNumber: "mt-px flex size-5 shrink-0 items-center justify-center rounded-full bg-secondary text-[11px] font-bold text-secondary-foreground",
+    popoverFooter: "mt-3.5 flex items-center justify-between gap-2 border-t border-border pt-3",
+    strip: "rounded-2xl border border-border bg-card px-4 py-4 shadow-sm sm:px-5",
+    stripTitle: "text-[15px] font-semibold",
+    stripSummary: "text-[13px] text-muted-foreground",
+    stripTile: "flex min-h-[6.5rem] flex-col gap-2 rounded-xl border border-border bg-background p-3",
+    stripTileNext: "border-primary/35 bg-primary/5",
+    launcher: "relative inline-flex h-9 shrink-0 items-center gap-2 rounded-full border border-border bg-background py-0 pr-2.5 pl-1.5 text-[13px] font-semibold shadow-sm transition-colors hover:border-primary/40 hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none",
+    launcherBadge: "absolute -top-3 -right-2 rounded-full bg-primary px-1.5 py-0.5 text-xs leading-none font-semibold text-primary-foreground shadow-md",
+    blocked: "px-1.5 text-xs text-muted-foreground",
+    srOnly: "sr-only",
+};
+/** The dark band's background. Replaceable outright; `{}` falls back to the card. */
+export const SETUP_BAND_STYLE = {
+    background: [
+        "radial-gradient(120% 70% at 0% 0%, color-mix(in oklab, var(--primary) 22%, transparent), transparent 55%)",
+        "radial-gradient(90% 60% at 100% 100%, color-mix(in oklab, var(--primary) 12%, transparent), transparent 60%)",
+        "#0e2f27",
+    ].join(", "),
+};
+//# sourceMappingURL=class-names.js.map

package/dist/setup-guide/class-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"class-names.js","sourceRoot":"","sources":["../../src/setup-guide/class-names.ts"],"names":[],"mappings":"AAiEA,MAAM,CAAC,MAAM,uBAAuB,GAAyB;IAC3D,IAAI,EAAE,oEAAoE;IAC1E,IAAI,EAAE,qCAAqC;IAC3C,WAAW,EAAE,gEAAgE;IAC7E,SAAS,EAAE,qEAAqE;IAChF,QAAQ,EAAE,6CAA6C;IACvD,SAAS,EAAE,gBAAgB;IAC3B,QAAQ,EAAE,iEAAiE;IAC3E,eAAe,EACb,yGAAyG;IAC3G,KAAK,EAAE,2BAA2B;IAClC,YAAY,EAAE,uBAAuB;IACrC,SAAS,EAAE,+BAA+B;IAC1C,GAAG,EAAE,kHAAkH;IACvH,OAAO,EAAE,yEAAyE;IAClF,QAAQ,EAAE,2BAA2B;IACrC,YAAY,EAAE,uBAAuB;IACrC,cAAc,EAAE,gEAAgE;IAChF,MAAM,EAAE,2EAA2E;IACnF,MAAM,EAAE,2FAA2F;IACnG,UAAU,EAAE,oCAAoC;IAChD,UAAU,EAAE,2DAA2D;IACvE,WAAW,EAAE,0DAA0D;IACvE,UAAU,EAAE,+EAA+E;IAC3F,IAAI,EAAE,wKAAwK;IAC9K,UAAU,EACR,sHAAsH;IACxH,cAAc,EAAE,+CAA+C;IAC/D,QAAQ,EAAE,wCAAwC;IAClD,GAAG,EAAE,sDAAsD;IAC3D,OAAO,EAAE,mDAAmD;IAC5D,OAAO,EAAE,2BAA2B;IACpC,WAAW,EAAE,YAAY;IACzB,eAAe,EAAE,gBAAgB;IACjC,WAAW,EAAE,cAAc;IAC3B,eAAe,EAAE,aAAa;IAC9B,MAAM,EACJ,sNAAsN;IACxN,aAAa,EAAE,wDAAwD;IACvE,aAAa,EAAE,qCAAqC;IACpD,WAAW,EAAE,4DAA4D;IACzE,UAAU,EACR,gNAAgN;IAClN,OAAO,EACL,kHAAkH;IACpH,YAAY,EAAE,uBAAuB;IACrC,WAAW,EAAE,yCAAyC;IACtD,aAAa,EACX,kIAAkI;IACpI,aAAa,EAAE,4EAA4E;IAC3F,KAAK,EAAE,sEAAsE;IAC7E,UAAU,EAAE,2BAA2B;IACvC,YAAY,EAAE,mCAAmC;IACjD,SAAS,EAAE,sFAAsF;IACjG,aAAa,EAAE,gCAAgC;IAC/C,QAAQ,EACN,+RAA+R;IACjS,aAAa,EACX,qIAAqI;IACvI,OAAO,EAAE,sCAAsC;IAC/C,MAAM,EAAE,SAAS;CAClB,CAAC;AAEF,qFAAqF;AACrF,MAAM,CAAC,MAAM,gBAAgB,GAA2B;IACtD,UAAU,EAAE;QACV,2GAA2G;QAC3G,8GAA8G;QAC9G,SAAS;KACV,CAAC,IAAI,CAAC,IAAI,CAAC;CACb,CAAC"}

package/dist/setup-guide/context.d.ts

@@ -0,0 +1,89 @@
+import * as React from "react";
+import type { SetupGuide, SetupReward } from "./guide.js";
+/**
+ * The guide, shared by everything that draws it: a launcher in the header, a
+ * card on the home page, a strip on each screen where steps are done.
+ *
+ * The host reads the guide on the server and hands it in. What is *done* is
+ * always the server's answer — this never decides that. Paying for it is a
+ * separate request, made when the server's answer shows something done and
+ * unpaid, or shortly after any save, so the reward lands while the person is
+ * still looking at what earned it.
+ *
+ * Two things are deliberately the host's: the transport (this package makes no
+ * HTTP requests and knows no routes) and what a reward is called. MAS has no
+ * credits; an app that gives nothing at all passes steps with no reward and
+ * gets a checklist that still works.
+ */
+export interface SetupSyncResult {
+    guide: SetupGuide;
+    rewards: SetupReward[];
+}
+export interface SetupGuideTransport {
+    /**
+     * Pay for everything done and unpaid, and answer with the guide as it now
+     * stands. `null` means the request did not succeed — the provider keeps what
+     * it has and says nothing, because a failed sync is not the person's problem
+     * and will be retried by the next save.
+     */
+    sync: (pathway: string) => Promise<SetupSyncResult | null>;
+    /** Hide the guide, or bring it back. `false` means it did not take. */
+    setHidden: (pathway: string, hidden: boolean) => Promise<boolean>;
+}
+/** What one of these is called, singular and plural. */
+export interface RewardWords {
+    one: string;
+    many: string;
+}
+export declare const DEFAULT_REWARD_WORDS: RewardWords;
+export declare function rewardWord(count: number, words: RewardWords): string;
+export interface SetupLinkProps {
+    href: string;
+    children: React.ReactNode;
+    className?: string;
+    onClick?: () => void;
+    target?: string;
+    rel?: string;
+    title?: string;
+    "aria-label"?: string;
+}
+/**
+ * How a link is drawn. The default is a plain `<a>`, which works everywhere and
+ * costs a full page load; an app with a router passes its own so the guide
+ * navigates the way the rest of the app does.
+ */
+export type SetupLinkComponent = (props: SetupLinkProps) => React.ReactNode;
+export interface SetupGuideState {
+    guide: SetupGuide | null;
+    /** Somebody viewing this account rather than living in it: shown, never paid or changed. */
+    readOnly: boolean;
+    words: RewardWords;
+    Link: SetupLinkComponent;
+    panelOpen: boolean;
+    setPanelOpen: (open: boolean) => void;
+    setHidden: (hidden: boolean) => Promise<void>;
+    /** Paid a moment ago, for the launcher to flash. */
+    justEarned: number | null;
+}
+/** Null outside the provider, and for accounts with no guide — every part checks. */
+export declare function useSetupGuide(): SetupGuideState | null;
+export interface SetupGuideProviderProps {
+    initial: SetupGuide | null;
+    transport: SetupGuideTransport;
+    readOnly?: boolean;
+    words?: RewardWords;
+    /**
+     * A window event the app fires after a successful write. Without one the
+     * guide only catches up when the page is read again, which is correct but
+     * slower — the reward lands on the next navigation rather than in front of
+     * the person who earned it.
+     */
+    changeEvent?: string;
+    settleMs?: number;
+    /** Called when bringing a hidden guide back, which needs a fresh read. */
+    onRefresh?: () => void;
+    link?: SetupLinkComponent;
+    children: React.ReactNode;
+}
+export declare function SetupGuideProvider({ initial, transport, readOnly, words, changeEvent, settleMs, onRefresh, link, children, }: SetupGuideProviderProps): React.JSX.Element;
+//# sourceMappingURL=context.d.ts.map

package/dist/setup-guide/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/setup-guide/context.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAC3D,uEAAuE;IACvE,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,oBAAoB,EAAE,WAAgD,CAAC;AAEpF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAEpE;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,KAAK,CAAC,SAAS,CAAC;AAI5E,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,4FAA4F;IAC5F,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,oDAAoD;IACpD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAID,qFAAqF;AACrF,wBAAgB,aAAa,IAAI,eAAe,GAAG,IAAI,CAEtD;AAOD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,kBAAkB,CAAC,EACjC,OAAO,EACP,SAAS,EACT,QAAgB,EAChB,KAA4B,EAC5B,WAAW,EACX,QAAoB,EACpB,SAAS,EACT,IAAgB,EAChB,QAAQ,GACT,EAAE,uBAAuB,qBAgHzB"}

package/dist/setup-guide/context.js

@@ -0,0 +1,124 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { useActionReporter } from "../ux/feedback.js";
+export const DEFAULT_REWARD_WORDS = { one: "credit", many: "credits" };
+export function rewardWord(count, words) {
+    return count === 1 ? words.one : words.many;
+}
+const PlainLink = ({ children, ...rest }) => _jsx("a", { ...rest, children: children });
+const SetupGuideContext = React.createContext(null);
+/** Null outside the provider, and for accounts with no guide — every part checks. */
+export function useSetupGuide() {
+    return React.useContext(SetupGuideContext);
+}
+/** Long enough that a burst of saves asks one question rather than five. */
+const SETTLE_MS = 1200;
+/** How long the launcher keeps showing what just landed. */
+const FLASH_MS = 4000;
+export function SetupGuideProvider({ initial, transport, readOnly = false, words = DEFAULT_REWARD_WORDS, changeEvent, settleMs = SETTLE_MS, onRefresh, link = PlainLink, children, }) {
+    const report = useActionReporter();
+    const [guide, setGuide] = React.useState(initial);
+    // A fresh reading from the server replaces ours: it knows things we cannot,
+    // like a learner added in another tab.
+    const [seen, setSeen] = React.useState(initial);
+    if (initial !== seen) {
+        setSeen(initial);
+        setGuide(initial);
+    }
+    const [panelOpen, setPanelOpen] = React.useState(false);
+    const [justEarned, setJustEarned] = React.useState(null);
+    const inFlight = React.useRef(false);
+    const pathway = guide?.pathway ?? null;
+    const listening = Boolean(guide && !guide.hidden && !guide.complete && !readOnly && changeEvent);
+    // Read through a ref so the sync function's identity never changes, and the
+    // listeners below are not torn down and rebuilt on every render.
+    const latest = React.useRef({ transport, words, report });
+    React.useEffect(() => {
+        latest.current = { transport, words, report };
+    });
+    const sync = React.useCallback(async () => {
+        if (!pathway || inFlight.current)
+            return;
+        inFlight.current = true;
+        const { transport: post, words: said, report: tell } = latest.current;
+        let result = null;
+        try {
+            result = await post.sync(pathway);
+        }
+        finally {
+            inFlight.current = false;
+        }
+        if (!result)
+            return;
+        setGuide(result.guide);
+        const earned = result.rewards.reduce((total, reward) => total + reward.reward, 0);
+        if (result.rewards.length === 0 || earned === 0)
+            return;
+        setJustEarned(earned);
+        const left = result.guide.totalReward - result.guide.earnedReward;
+        const what = result.rewards.length === 1
+            ? (result.rewards[0]?.title ?? "A setup step")
+            : `${result.rewards.length} steps done`;
+        tell({
+            tone: "success",
+            title: `+${earned} ${rewardWord(earned, said)} — ${what}`,
+            description: left > 0
+                ? `${result.guide.earnedReward} of ${result.guide.totalReward} earned so far — ${left} more to earn.`
+                : `All ${result.guide.totalReward} earned, and they are yours to keep.`,
+        });
+    }, [pathway]);
+    // Something done and not yet paid, as the server reads it: pay for it now.
+    // Deferred rather than called straight from the effect, which would be
+    // setting state during an effect's own render pass.
+    const pending = guide && !guide.hidden && !readOnly ? guide.pendingKeys.join(",") : "";
+    React.useEffect(() => {
+        if (!pending)
+            return;
+        const timer = setTimeout(() => void sync(), 0);
+        return () => clearTimeout(timer);
+    }, [pending, sync]);
+    // Most saves never refresh the page, so ask once the saving has settled.
+    React.useEffect(() => {
+        if (!listening || !changeEvent)
+            return;
+        let timer;
+        const onChange = () => {
+            clearTimeout(timer);
+            timer = setTimeout(() => void sync(), settleMs);
+        };
+        window.addEventListener(changeEvent, onChange);
+        return () => {
+            clearTimeout(timer);
+            window.removeEventListener(changeEvent, onChange);
+        };
+    }, [listening, changeEvent, settleMs, sync]);
+    React.useEffect(() => {
+        if (justEarned === null)
+            return;
+        const timer = setTimeout(() => setJustEarned(null), FLASH_MS);
+        return () => clearTimeout(timer);
+    }, [justEarned]);
+    const setHidden = React.useCallback(async (hidden) => {
+        if (!pathway || readOnly)
+            return;
+        // Optimistic: hiding something should feel like closing it, not like
+        // asking permission to close it.
+        setGuide((current) => (current ? { ...current, hidden } : current));
+        const ok = await latest.current.transport.setHidden(pathway, hidden);
+        if (!ok) {
+            setGuide((current) => (current ? { ...current, hidden: !hidden } : current));
+            latest.current.report({ tone: "error", title: "Could not change the setup guide" });
+            return;
+        }
+        if (hidden)
+            setPanelOpen(false);
+        // A hidden guide skipped working out what was done, so bringing it back
+        // needs the server asked again.
+        else
+            onRefresh?.();
+    }, [pathway, readOnly, onRefresh]);
+    const value = React.useMemo(() => ({ guide, readOnly, words, Link: link, panelOpen, setPanelOpen, setHidden, justEarned }), [guide, readOnly, words, link, panelOpen, setHidden, justEarned]);
+    return _jsx(SetupGuideContext.Provider, { value: value, children: children });
+}
+//# sourceMappingURL=context.js.map

package/dist/setup-guide/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/setup-guide/context.tsx"],"names":[],"mappings":"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"}

package/dist/setup-guide/guide.d.ts

@@ -0,0 +1,159 @@
+/**
+ * What a new account is asked to do, how far through it is, and what that has
+ * earned. No React and no DOM, so the rules are tested without a browser and
+ * hold whatever draws them.
+ *
+ * **Nothing about progress is stored.** A step is *done* when the account holds
+ * what it asks for — a learner, a price, a published course — however it got
+ * there; the host reads that fresh each time. What *is* stored is the reward:
+ * one entry per step per account, keyed on the step, so a step pays once
+ * however many times its thing is made, deleted and made again. That split is
+ * the whole design, and it is why `done` and `earned` arrive here as two
+ * separate sets rather than one status per step.
+ *
+ * A step key is permanent. Rewards are keyed on it, so renaming one pays
+ * everybody a second time.
+ */
+import type { ReactNode } from "react";
+/** Short numbered instructions. `**bold**` marks the app's own labels, `_italic_` an example. */
+export interface SetupHowTo {
+    title: string;
+    steps: readonly string[];
+}
+/** Where to read more. Rendered as a link, so the host decides what the href means. */
+export interface SetupGuideLink {
+    href: string;
+    title: string;
+}
+export interface SetupStepDef {
+    /** Stable forever: rewards are keyed on it. */
+    key: string;
+    title: string;
+    /** What finishing it pays. Omit, or 0, for a step that is progress only. */
+    reward?: number;
+    how?: SetupHowTo;
+    guide?: SetupGuideLink;
+}
+export interface SetupItemDef {
+    key: string;
+    title: string;
+    description?: string;
+    /** Drawn beside the title. The host's own icon element, so this package needs no icon set of its own. */
+    icon?: ReactNode;
+    /** Where the item is done. */
+    href: string;
+    actionLabel: string;
+    /**
+     * The screen that shows this item's steps, when it has several. Everywhere
+     * else shows the item's progress and a way here.
+     */
+    screen?: string;
+    /**
+     * Step keys that must be done before this item can be started. An item nobody
+     * can start yet says so instead of offering a button that leads nowhere useful.
+     */
+    requires?: readonly string[];
+    /** What to say while it is blocked, e.g. "After your first learner". */
+    blockedLabel?: string;
+    /**
+     * Its rewards land only once the whole thing is built — for a flow that saves
+     * nothing before its last step, so the steps tick as choices are made and pay
+     * at the end.
+     */
+    paysOnComplete?: boolean;
+    steps: readonly SetupStepDef[];
+}
+export interface GuideStep extends SetupStepDef {
+    /** The account holds what the step asks for. */
+    done: boolean;
+    /** Its reward has been paid. */
+    earned: boolean;
+    /** Always a number here, whatever the definition left out. */
+    reward: number;
+}
+export interface GuideItem extends Omit<SetupItemDef, "steps"> {
+    steps: GuideStep[];
+    reward: number;
+    earnedReward: number;
+    doneCount: number;
+    done: boolean;
+    /** Why it cannot be started yet, when it cannot. */
+    blocked: string | null;
+}
+export interface SetupGuide {
+    /** Which set of steps this is — the host's own name for it. */
+    pathway: string;
+    items: GuideItem[];
+    totalReward: number;
+    earnedReward: number;
+    doneItems: number;
+    /** The first item not done and not blocked — what the guide leads with. */
+    nextKey: string | null;
+    /** Every step done and paid. */
+    complete: boolean;
+    /** Done but not yet paid. A sync would pay exactly these. */
+    pendingKeys: string[];
+    hidden: boolean;
+}
+/** What one step paid, for announcing it. */
+export interface SetupReward {
+    key: string;
+    title: string;
+    reward: number;
+}
+export interface BuildGuideInput {
+    pathway: string;
+    items: readonly SetupItemDef[];
+    /** Step keys the account's own records satisfy. */
+    done: ReadonlySet<string>;
+    /** Step keys already paid for. */
+    earned: ReadonlySet<string>;
+    hidden?: boolean;
+}
+/** Every step of every item, in order. */
+export declare function stepsOf(items: readonly SetupItemDef[]): SetupStepDef[];
+/** Every step key, for checking what a request names before trusting it. */
+export declare function stepKeysOf(items: readonly SetupItemDef[]): Set<string>;
+/** The guide as it stands for one account. Pure: the same inputs always give the same answer. */
+export declare function buildGuide({ pathway, items, done, earned, hidden }: BuildGuideInput): SetupGuide;
+export declare function findItem(guide: SetupGuide | null | undefined, key: string): GuideItem | null;
+/**
+ * What counts as done: what the records show now, plus everything already paid
+ * for.
+ *
+ * A reward, once earned, is not taken back — so a step whose thing has since
+ * been deleted stays ticked rather than reopening and asking to be paid a
+ * second time. Hosts pass the result of this as `done`.
+ */
+export declare function doneSteps(facts: ReadonlySet<string>, earned: ReadonlySet<string>): Set<string>;
+/**
+ * The steps this account has done and not been paid for — what a sync owes it.
+ *
+ * Kept here, away from the database, because *which* steps are owed is a rule
+ * and writing the entries is a transaction. The host loops over this and writes
+ * one row each, letting its unique index refuse a second payment: two tabs
+ * asking at the same moment both get this list, and only one of them gets to
+ * write each row.
+ */
+export declare function rewardsOwed(items: readonly SetupItemDef[], done: ReadonlySet<string>, earned: ReadonlySet<string>): SetupReward[];
+export interface ItemProgress {
+    /** Done, plus anything `ready` counts as good as done. */
+    progressed: number;
+    total: number;
+    percent: number;
+    /** The first step neither done nor ready. */
+    nextKey: string | null;
+}
+/**
+ * How far through one item is.
+ *
+ * `ready` is for a flow that saves nothing until its last step: its choices are
+ * made but nothing exists yet, so they tick without being done. They count
+ * towards the bar — the point of the bar is to show the end approaching — but
+ * never towards what has been earned.
+ */
+export declare function itemProgress(item: GuideItem, ready?: ReadonlySet<string>): ItemProgress;
+/** How a step reads: done, ready to be paid, the one to do next, or still to do. */
+export type StepState = "done" | "ready" | "next" | "todo";
+export declare function stepState(step: GuideStep, nextKey: string | null, ready?: ReadonlySet<string>): StepState;
+//# sourceMappingURL=guide.d.ts.map

package/dist/setup-guide/guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../../src/setup-guide/guide.ts"],"names":[],"mappings":"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"}

package/dist/setup-guide/guide.js

@@ -0,0 +1,128 @@
+/**
+ * What a new account is asked to do, how far through it is, and what that has
+ * earned. No React and no DOM, so the rules are tested without a browser and
+ * hold whatever draws them.
+ *
+ * **Nothing about progress is stored.** A step is *done* when the account holds
+ * what it asks for — a learner, a price, a published course — however it got
+ * there; the host reads that fresh each time. What *is* stored is the reward:
+ * one entry per step per account, keyed on the step, so a step pays once
+ * however many times its thing is made, deleted and made again. That split is
+ * the whole design, and it is why `done` and `earned` arrive here as two
+ * separate sets rather than one status per step.
+ *
+ * A step key is permanent. Rewards are keyed on it, so renaming one pays
+ * everybody a second time.
+ */
+const rewardOf = (step) => step.reward ?? 0;
+const sum = (numbers) => numbers.reduce((total, n) => total + n, 0);
+/** Every step of every item, in order. */
+export function stepsOf(items) {
+    return items.flatMap((item) => [...item.steps]);
+}
+/** Every step key, for checking what a request names before trusting it. */
+export function stepKeysOf(items) {
+    return new Set(stepsOf(items).map((step) => step.key));
+}
+/**
+ * Whether an item can be started yet.
+ *
+ * Only while nothing of it is done: an item that somehow got started stays
+ * open, because telling somebody they cannot do a thing they have half done is
+ * worse than a requirement quietly not applying.
+ */
+function blockedBy(item, done, doneCount) {
+    if (doneCount > 0 || !item.requires?.length)
+        return null;
+    const unmet = item.requires.some((key) => !done.has(key));
+    return unmet ? (item.blockedLabel ?? "Not yet") : null;
+}
+/** The guide as it stands for one account. Pure: the same inputs always give the same answer. */
+export function buildGuide({ pathway, items, done, earned, hidden = false }) {
+    const built = items.map((def) => {
+        const steps = def.steps.map((step) => ({
+            ...step,
+            reward: rewardOf(step),
+            done: done.has(step.key),
+            earned: earned.has(step.key),
+        }));
+        const doneCount = steps.filter((step) => step.done).length;
+        return {
+            ...def,
+            steps,
+            reward: sum(steps.map((step) => step.reward)),
+            earnedReward: sum(steps.filter((step) => step.earned).map((step) => step.reward)),
+            doneCount,
+            // An item with no steps at all is not "done" — it has nothing to be done about.
+            done: steps.length > 0 && doneCount === steps.length,
+            blocked: blockedBy(def, done, doneCount),
+        };
+    });
+    const all = built.flatMap((item) => item.steps);
+    return {
+        pathway,
+        items: built,
+        totalReward: sum(all.map((step) => step.reward)),
+        earnedReward: sum(all.filter((step) => step.earned).map((step) => step.reward)),
+        doneItems: built.filter((item) => item.done).length,
+        nextKey: built.find((item) => !item.done && !item.blocked)?.key ?? null,
+        complete: all.length > 0 && all.every((step) => step.done && step.earned),
+        pendingKeys: all.filter((step) => step.done && !step.earned).map((step) => step.key),
+        hidden,
+    };
+}
+export function findItem(guide, key) {
+    return guide?.items.find((item) => item.key === key) ?? null;
+}
+/**
+ * What counts as done: what the records show now, plus everything already paid
+ * for.
+ *
+ * A reward, once earned, is not taken back — so a step whose thing has since
+ * been deleted stays ticked rather than reopening and asking to be paid a
+ * second time. Hosts pass the result of this as `done`.
+ */
+export function doneSteps(facts, earned) {
+    return new Set([...facts, ...earned]);
+}
+/**
+ * The steps this account has done and not been paid for — what a sync owes it.
+ *
+ * Kept here, away from the database, because *which* steps are owed is a rule
+ * and writing the entries is a transaction. The host loops over this and writes
+ * one row each, letting its unique index refuse a second payment: two tabs
+ * asking at the same moment both get this list, and only one of them gets to
+ * write each row.
+ */
+export function rewardsOwed(items, done, earned) {
+    return stepsOf(items)
+        .filter((step) => done.has(step.key) && !earned.has(step.key) && rewardOf(step) > 0)
+        .map((step) => ({ key: step.key, title: step.title, reward: rewardOf(step) }));
+}
+/**
+ * How far through one item is.
+ *
+ * `ready` is for a flow that saves nothing until its last step: its choices are
+ * made but nothing exists yet, so they tick without being done. They count
+ * towards the bar — the point of the bar is to show the end approaching — but
+ * never towards what has been earned.
+ */
+export function itemProgress(item, ready) {
+    const isReady = (step) => !step.done && Boolean(ready?.has(step.key));
+    const progressed = item.steps.filter((step) => step.done || isReady(step)).length;
+    const total = item.steps.length;
+    return {
+        progressed,
+        total,
+        percent: total === 0 ? 0 : Math.round((progressed / total) * 100),
+        nextKey: item.steps.find((step) => !step.done && !isReady(step))?.key ?? null,
+    };
+}
+export function stepState(step, nextKey, ready) {
+    if (step.done)
+        return "done";
+    if (ready?.has(step.key))
+        return "ready";
+    return step.key === nextKey ? "next" : "todo";
+}
+//# sourceMappingURL=guide.js.map

package/dist/setup-guide/guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.js","sourceRoot":"","sources":["../../src/setup-guide/guide.ts"],"names":[],"mappings":"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"}

package/dist/setup-guide/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `@connextar/house/setup-guide` — the checklist a new account works through,
+ * and what finishing a step earns.
+ *
+ * It exists because the hard parts are not the checklist. They are: knowing
+ * what is done without storing it (so a thing made any other way still counts),
+ * paying for it exactly once however many tabs ask at the same moment, and
+ * saying so while the person is still looking at what they just did. Those are
+ * the same three problems in every app, and they have one right answer each.
+ *
+ * What the host supplies is everything that is genuinely its own: the steps,
+ * how each one is read from its records, where the reward is written, and what
+ * a reward is even called. This package holds no routes, makes no requests,
+ * imports no toast library and knows nothing about a database.
+ *
+ * The three surfaces are a card for a home page, a strip for the screen where
+ * an item's steps are actually done, and a launcher for the header. The panel
+ * the launcher opens is the app's own sheet — see `launcher.tsx`.
+ */
+export { buildGuide, doneSteps, findItem, itemProgress, rewardsOwed, stepKeysOf, stepState, stepsOf, type BuildGuideInput, type GuideItem, type GuideStep, type ItemProgress, type SetupGuide, type SetupGuideLink, type SetupHowTo, type SetupItemDef, type SetupReward, type SetupStepDef, type StepState, } from "./guide.js";
+export { DEFAULT_REWARD_WORDS, rewardWord, SetupGuideProvider, useSetupGuide, type RewardWords, type SetupGuideProviderProps, type SetupGuideState, type SetupGuideTransport, type SetupLinkComponent, type SetupLinkProps, type SetupSyncResult, } from "./context.js";
+export { SETUP_BAND_STYLE, SETUP_GUIDE_CLASS_NAMES, type SetupGuideClassNames } from "./class-names.js";
+export { GuideIconLink, HowText, HowToButton, ItemHelp, MiniProgress, ProgressRing, RewardChip, RewardRing, Segments, StepCircle, useClassNames, type ClassNameOverrides, type RewardState, } from "./bits.js";
+export { SetupCard, type SetupActions, type SetupCardProps } from "./card.js";
+export { SetupStrip, type SetupStripProps } from "./strip.js";
+export { SetupGuideList, SetupGuideSummary, SetupLauncherButton } from "./launcher.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/setup-guide/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/setup-guide/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,UAAU,EACV,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,UAAU,EACV,SAAS,EACT,OAAO,EACP,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExG,OAAO,EACL,aAAa,EACb,OAAO,EACP,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,EACV,QAAQ,EACR,UAAU,EACV,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,WAAW,GACjB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}