@posthog/twig-components 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PostHog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -0,0 +1,59 @@
+# Twig components
+
+`@posthog/twig-components` holds reusable pieces of the fictional Twig travel site and its PostHog playground. It is a React package, not a complete website.
+
+| Need | Start here |
+| --- | --- |
+| Find a component, its purpose, props, and current use | [Component reference](docs/components.md) |
+| Contribute with a coding agent | [Agent guidance](AGENTS.md) |
+| Report a security issue | [Private vulnerability reporting](https://github.com/PostHog/twig-components/security/advisories/new) |
+| Decide which repo to change for a new lab or guide | [Integration and authoring scenarios](docs/integration.md#authoring-scenarios) |
+| Understand package setup and updates | [Integration and updates](docs/integration.md) |
+| Develop and click through components | [Workbench guide](docs/workbench.md) |
+| See static release snapshots | `npm run gallery`, then open `gallery/output/index.html` |
+
+## How it fits
+
+```mermaid
+flowchart LR
+    package["twig-components<br/>UI, data, lab logic, styles"]
+    twig["twig.com<br/>pages and routing"]
+    guide["posthog.com<br/>PostHog 101 guide"]
+    package --> twig
+    package -. "planned read-only Twig views" .-> guide
+```
+
+**Current status:** Twig.com imports a local workspace copy of this package. The standalone package is not published to npm. PostHog 101 does not yet import it. See [integration and updates](docs/integration.md) before changing either site.
+
+## Quick example
+
+`BrowseStaysPreview` is a static Twig excerpt for an article. `selected` controls which filter and stay it shows; it does not handle clicks or record events.
+
+```tsx
+import { BrowseStaysPreview } from "@posthog/twig-components/browse-stays-preview";
+import "@posthog/twig-components/catalog.css";
+
+<BrowseStaysPreview selected="Coast" />;
+```
+
+For the interactive website filters, use [`StayFilters`](docs/components.md#website-views-and-data) instead. For the five teaching labs and playground shell, see [labs and playground](docs/components.md#labs-and-playground).
+
+## Work locally
+
+```sh
+npm ci
+npm run workbench
+```
+
+Open the URL printed in the terminal. The workbench shows Twig views and all five labs, with local fixtures you can click through. See the [workbench guide](docs/workbench.md) for adding a component or lab preview. The gallery remains a static snapshot for release review.
+
+Before asking for review:
+
+```sh
+npm test
+npm run workbench:build
+npm run gallery
+npm pack --dry-run
+```
+
+`npm test` builds the package and runs its tests. `workbench:build` checks the live preview. `npm pack --dry-run` lists the files a release would contain. Changes here do not update either website automatically.

package/build-assets.mjs

@@ -0,0 +1,18 @@
+import { copyFile, mkdir } from "node:fs/promises";
+await mkdir(new URL("./dist/assets/", import.meta.url), { recursive: true });
+for (const [source, target] of [
+  ["./src/catalog.css", "catalog.css"],
+  ["./src/lab.css", "lab.css"],
+  ["./assets/Halfre.ttf", "assets/Halfre.ttf"],
+  ["./assets/logo.svg", "assets/logo.svg"],
+  ["./assets/cliff.png", "assets/cliff.png"],
+  ["./assets/cabin.jpg", "assets/cabin.jpg"],
+  ["./assets/RoundHog.woff2", "assets/RoundHog.woff2"],
+  ["./assets/RoundHog-Medium.woff2", "assets/RoundHog-Medium.woff2"],
+  ["./assets/RoundHog-SemiBold.woff2", "assets/RoundHog-SemiBold.woff2"],
+]) {
+  await copyFile(
+    new URL(source, import.meta.url),
+    new URL(`./dist/${target}`, import.meta.url)
+  );
+}

package/dist/AiLab.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+import { type AiAction, type AiScenario, type AiState } from "./ai-lab.js";
+type Lesson = "example" | "observe" | "repair" | "timeout" | "explore";
+export declare function AiLabProvider({ children, active, }: {
+    children: ReactNode;
+    active: boolean;
+}): import("react").JSX.Element;
+export declare const useAiLab: () => {
+    state: AiState;
+    dispatch: (action: AiAction) => void;
+    active: boolean;
+    scenario: AiScenario;
+    setScenario: (scenario: AiScenario) => void;
+    lesson: Lesson;
+    setLesson: (lesson: Lesson) => void;
+};
+export declare function useResetAiLab(): () => void;
+export declare function AiIntroduction({ onContinue }: {
+    onContinue: () => void;
+}): import("react").JSX.Element;
+export declare function AiLab({ stage, onStage, onFocusPlanner, }: {
+    stage: number;
+    onStage: (stage: number) => void;
+    onFocusPlanner: () => void;
+}): import("react").JSX.Element;
+export {};

package/dist/AiLab.js

@@ -0,0 +1,140 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { LabChoices } from "./LabChoices.js";
+import { FinishLabButton } from "./FinishLabButton.js";
+import { LabChecklist } from "./LabChecklist.js";
+import { createContext, useContext, useReducer, useState, } from "react";
+import { aiReducer, recommendationEvidence, aiCode, fixtureRequest, initialAiState, } from "./ai-lab.js";
+const AiContext = createContext({
+    state: initialAiState,
+    dispatch: () => { },
+    active: false,
+    scenario: "success",
+    setScenario: () => { },
+    lesson: "example",
+    setLesson: () => { },
+});
+export function AiLabProvider({ children, active, }) {
+    const [state, dispatch] = useReducer(aiReducer, initialAiState);
+    const [scenario, setScenario] = useState("success");
+    const [lesson, setLesson] = useState("example");
+    return (_jsx(AiContext.Provider, { value: {
+            state,
+            dispatch,
+            active,
+            scenario,
+            setScenario,
+            lesson,
+            setLesson,
+        }, children: children }));
+}
+export const useAiLab = () => useContext(AiContext);
+export function useResetAiLab() {
+    const { dispatch, setScenario, setLesson } = useContext(AiContext);
+    return () => {
+        dispatch({ type: "reset" });
+        setScenario("success");
+        setLesson("example");
+    };
+}
+export function AiIntroduction({ onContinue }) {
+    return (_jsxs("div", { className: "vac-guide-intro", children: [_jsx("h3", { children: "Can you investigate a bad recommendation?" }), _jsx("p", { children: "A visitor says Twig suggested the wrong stay. What would you need to see to investigate?" }), _jsx("div", { className: "vac-guide-example vac-guide-lesson", children: _jsx("p", { children: "Follow a request from Twig into a captured event. Then connect the model\u2019s response and see the difference." }) }), _jsx("p", { children: "The goal: compare what the visitor asked with what Twig recommended." }), _jsx("button", { className: "vac-button", onClick: onContinue, children: _jsx("span", { className: "vac-os-button-face", children: "See the worked example \u2192" }) }), _jsxs("details", { className: "vac-lab-step", children: [_jsx("summary", { children: "How this simulation works" }), _jsx("p", { children: "Twig uses a preset request and recommendation. You\u2019re changing what gets recorded, not the recommendation itself. No model runs and nothing is sent to PostHog." })] })] }));
+}
+const fields = [
+    { key: "input", label: "Request", detail: "$ai_input" },
+    { key: "output", label: "Response", detail: "$ai_output_choices" },
+    { key: "linked", label: "Trip trace ID", detail: "$ai_trace_id" },
+    { key: "errors", label: "Error details", detail: "$ai_is_error + $ai_error" },
+];
+function CaptureMapping({ config }) {
+    return (_jsxs("div", { className: "vac-ai-mapping", children: [_jsx("span", { className: "vac-muted", children: "Inside the generation event\u2019s properties" }), _jsx("pre", { children: _jsxs("code", { children: ["{\n", config.input && (_jsx("mark", { className: config.output ? "vac-ai-code-context" : "vac-ai-code-highlight", children: '  $ai_input: [\n    { role: "user", content: request }\n  ],\n' })), config.output && (_jsx("mark", { className: "vac-ai-code-highlight", children: '  $ai_output_choices: [\n    { role: "assistant", content: response }\n  ],\n' })), "  // Other fields omitted\n}"] }) })] }));
+}
+export function AiLab({ stage, onStage, onFocusPlanner, }) {
+    const { state, dispatch, scenario, setScenario, lesson, setLesson } = useContext(AiContext);
+    const [selected, select] = useState(null);
+    const run = selected && state.runs.includes(selected) ? selected : state.runs.at(-1);
+    return (_jsxs("section", { className: "vac-lab vac-builder vac-ai-lab", children: [stage === 1 ? (_jsx(_Fragment, { children: lesson === "example" ? (_jsxs(_Fragment, { children: [_jsx("h3", { children: "From Twig to an event" }), _jsxs("div", { className: "vac-ai-compare", children: [_jsx("h4", { children: "Twig\u2019s request" }), _jsx("p", { children: fixtureRequest })] }), _jsxs("p", { children: ["The app holds that text in ", _jsx("code", { children: "request" }), ". This capture code puts it in PostHog\u2019s ", _jsx("code", { children: "$ai_input" }), " field."] }), _jsx(CaptureMapping, { config: initialAiState.config }), _jsx("p", { children: "Run it once to see those values in the recorded event." }), _jsx("button", { className: "vac-button", onClick: () => {
+                                dispatch({ type: "edit", config: initialAiState.config });
+                                dispatch({ type: "apply" });
+                                setScenario("success");
+                                setLesson("observe");
+                                onFocusPlanner();
+                            }, children: _jsx("span", { className: "vac-os-button-face", children: "Apply the code \u2192" }) })] })) : !state.applied ? (_jsxs(_Fragment, { children: [_jsx("h3", { children: lesson === "repair"
+                                ? "Connect the response"
+                                : lesson === "timeout"
+                                    ? "Record a failed model request"
+                                    : "Explore captured fields" }), _jsx("p", { children: lesson === "repair" ? (_jsxs(_Fragment, { children: ["Twig holds the recommendation in ", _jsx("code", { children: "response" }), ". Connect it to ", _jsx("code", { children: "$ai_output_choices" }), " to record it too."] })) : lesson === "timeout" ? (_jsxs(_Fragment, { children: ["The next request will time out. Enable", " ", _jsx("strong", { children: "Error details" }), " to capture why it failed."] })) : ("Choose the fields that help answer your question. These fields are optional.") }), _jsxs("fieldset", { className: "vac-ai-fields", children: [_jsx("legend", { children: lesson === "repair"
+                                        ? "Add to the capture code"
+                                        : "Choose your fields" }), fields
+                                    .filter((field) => lesson === "repair"
+                                    ? field.key === "output"
+                                    : lesson === "timeout"
+                                        ? field.key === "errors"
+                                        : true)
+                                    .map((field) => (_jsxs("label", { children: [_jsx("input", { type: "checkbox", checked: state.config[field.key], onChange: (e) => dispatch({
+                                                type: "edit",
+                                                config: { [field.key]: e.target.checked },
+                                            }) }), _jsxs("span", { children: [lesson === "repair"
+                                                    ? "Record the model’s response"
+                                                    : field.label, _jsx("code", { children: field.detail })] })] }, field.key)))] }), lesson === "explore" && (_jsx(LabChoices, { label: "Response for the next exercise", value: scenario, onChange: setScenario, options: [
+                                { value: "success", label: "Recommendation" },
+                                { value: "timeout", label: "Provider timeout" },
+                            ] })), lesson === "timeout" ? (_jsx("pre", { children: state.config.errors
+                                ? `$ai_is_error: Boolean(error),\n$ai_error: error?.message`
+                                : "// Error fields are not captured yet" })) : (_jsx(CaptureMapping, { config: state.config })), lesson !== "timeout" && (_jsx("p", { className: "vac-muted", children: state.config.output
+                                ? "The highlighted response field will be included on the next run."
+                                : "The response field is absent from this capture code." })), _jsx("button", { className: "vac-button", disabled: (lesson === "repair" && !state.config.output) ||
+                                (lesson === "timeout" && !state.config.errors), onClick: () => {
+                                dispatch({ type: "apply" });
+                                onFocusPlanner();
+                            }, children: _jsx("span", { className: "vac-os-button-face", children: "Apply the change \u2192" }) })] })) : (_jsxs(_Fragment, { children: [_jsx("h3", { children: state.awaitingRun
+                                ? scenario === "timeout"
+                                    ? "Try the failed request on Twig"
+                                    : "Run the request on Twig"
+                                : "Your request is ready to review" }), _jsx("p", { children: state.awaitingRun ? (_jsxs(_Fragment, { children: ["Code applied. Click ", _jsx("strong", { children: "Run simulation" }), " in Twig\u2019s trip planner."] })) : ("The request has finished. Review what your capture code recorded.") }), _jsx(LabChecklist, { label: "AI exercise progress", items: [
+                                { label: "Apply the capture code", done: true },
+                                {
+                                    label: (_jsxs(_Fragment, { children: ["Click ", _jsx("strong", { children: "Run simulation" }), " on Twig"] })),
+                                    done: !state.awaitingRun,
+                                },
+                            ] }), state.awaitingRun ? (_jsx("button", { className: "vac-button", onClick: onFocusPlanner, children: _jsx("span", { className: "vac-os-button-face", children: "Show the trip planner \u2192" }) })) : (_jsx("button", { className: "vac-button", onClick: () => {
+                                select(null);
+                                onStage(2);
+                            }, children: _jsx("span", { className: "vac-os-button-face", children: "See what was recorded \u2192" }) }))] })) })) : (_jsxs(_Fragment, { children: [_jsx("h3", { children: run?.scenario === "timeout"
+                            ? "Review the failed request"
+                            : lesson === "observe"
+                                ? "Find the missing response"
+                                : "Compare the request and response" }), !run ? (_jsxs(_Fragment, { children: [_jsx("p", { children: "Run the worked example in the exercise first." }), _jsx("button", { className: "vac-button", onClick: () => onStage(1), children: _jsx("span", { className: "vac-os-button-face", children: "Continue the exercise \u2192" }) })] })) : (_jsxs(_Fragment, { children: [state.runs.length > 1 && (_jsx(LabChoices, { label: "Compare runs", value: run.id, onChange: (id) => select(state.runs.find((item) => item.id === id) ?? null), options: [...state.runs].reverse().map((item) => ({
+                                    value: item.id,
+                                    label: `Run ${item.id} · ${item.scenario === "success" ? "Recommendation" : "Timeout"}`,
+                                })) })), _jsxs("div", { className: "vac-ai-compare", children: [_jsx("h4", { children: "Recorded evidence" }), _jsxs("dl", { children: [_jsxs("dt", { children: ["Visitor\u2019s request \u00B7 ", _jsx("code", { children: "$ai_input" })] }), _jsx("dd", { children: run.config.input ? (_jsx("mark", { className: "vac-ai-code-highlight", children: run.prompt })) : ("Not captured") }), _jsx("dt", { children: run.response ? (_jsxs(_Fragment, { children: ["Model\u2019s response \u00B7 ", _jsx("code", { children: "$ai_output_choices" })] })) : ("Model error") }), _jsx("dd", { children: run.response ? (run.config.output ? (_jsx("mark", { className: "vac-ai-code-highlight", children: run.response })) : ("Not captured")) : run.config.errors ? ("Simulated provider timeout") : ("Not captured") })] })] }), _jsxs("div", { className: "vac-lab-output", role: "status", children: [lesson === "observe" && (_jsx("strong", { children: "Twig displayed a recommendation, but this code never recorded it." })), _jsx("p", { children: recommendationEvidence(run).explanation })] }), lesson === "timeout" &&
+                                run.scenario === "timeout" &&
+                                recommendationEvidence(run).complete ? (_jsx(FinishLabButton, { onClick: () => onStage(3) })) : (_jsx("button", { className: "vac-button", onClick: () => {
+                                    select(null);
+                                    const next = lesson === "observe"
+                                        ? "repair"
+                                        : lesson === "repair" &&
+                                            recommendationEvidence(run).complete
+                                            ? "timeout"
+                                            : lesson === "repair"
+                                                ? "repair"
+                                                : "explore";
+                                    setLesson(next);
+                                    setScenario(next === "timeout" ? "timeout" : "success");
+                                    dispatch({
+                                        type: "edit",
+                                        config: next === "repair"
+                                            ? { input: true, output: false }
+                                            : next === "timeout"
+                                                ? { input: true, output: true, errors: false }
+                                                : {},
+                                    });
+                                    onStage(1);
+                                }, children: _jsx("span", { className: "vac-os-button-face", children: lesson === "observe" ||
+                                        (lesson === "repair" &&
+                                            !recommendationEvidence(run).complete)
+                                        ? "Connect the missing response →"
+                                        : lesson === "repair"
+                                            ? "Record a failed request →"
+                                            : "Explore another configuration →" }) })), recommendationEvidence(run).complete && (_jsx("p", { className: "vac-muted", children: "You can now compare the request and outcome. This helps investigate a problem; it doesn\u2019t fix the model\u2019s answer." }))] }))] })), _jsxs("details", { className: "vac-lab-step", children: [_jsx("summary", { children: "Code and session options" }), _jsx("pre", { children: aiCode(stage === 2 && run ? run.config : state.applied ?? state.config) }), stage === 2 && run && (_jsxs(_Fragment, { children: [_jsx("h4", { children: "Captured event JSON" }), _jsx("pre", { children: JSON.stringify(run.event, null, 2) })] })), _jsx("a", { href: "https://posthog.com/docs/ai-observability/installation/manual-capture", target: "_blank", rel: "noreferrer", children: "Manual capture docs \u2197" }), _jsxs("div", { className: "vac-lab-actions", children: [stage === 1 && state.applied && lesson !== "observe" && (_jsx("button", { className: "vac-text-button", onClick: () => dispatch({ type: "edit", config: {} }), children: "Edit captured fields" })), state.runs.length > 0 && (_jsx("button", { className: "vac-text-button", onClick: () => dispatch({ type: "clear" }), children: "Clear runs" }))] })] })] }));
+}

package/dist/BookingLab.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode, type Dispatch, type SetStateAction } from "react";
+import { type TripSelection } from "./trip-dates.js";
+import { type BookingAction, type BookingState } from "./booking-lab.js";
+export declare function BookingLabProvider({ children, active, }: {
+    children: ReactNode;
+    active: boolean;
+}): import("react").JSX.Element;
+export declare const useBookingLab: () => {
+    state: BookingState;
+    dispatch: (action: BookingAction) => void;
+    active: boolean;
+    trip: TripSelection;
+    setTrip: Dispatch<SetStateAction<TripSelection>>;
+};
+export declare function BookingLab({ stage, onStage, onFocusBooking, }: {
+    stage: number;
+    onStage: (stage: number) => void;
+    onFocusBooking: () => void;
+}): import("react").JSX.Element;

package/dist/BookingLab.js

@@ -0,0 +1,100 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { LabChoices } from "./LabChoices.js";
+import { FinishLabButton } from "./FinishLabButton.js";
+import { createContext, useContext, useReducer, useState, } from "react";
+import { todayAtStay, validateTrip, } from "./trip-dates.js";
+import { bookingReducer, bookingCode, initialBookingState, } from "./booking-lab.js";
+const emptyTrip = { checkIn: "", checkOut: "", guests: "" };
+const BookingContext = createContext({
+    state: initialBookingState,
+    dispatch: () => { },
+    active: false,
+    trip: emptyTrip,
+    setTrip: () => { },
+});
+export function BookingLabProvider({ children, active, }) {
+    const [trip, setTrip] = useState(emptyTrip);
+    const [state, dispatch] = useReducer(bookingReducer, initialBookingState);
+    return (_jsx(BookingContext.Provider, { value: { state, dispatch, active, trip, setTrip }, children: children }));
+}
+export const useBookingLab = () => useContext(BookingContext);
+function Action({ children, onClick, }) {
+    return (_jsx("button", { type: "button", className: "vac-button", onClick: onClick, children: _jsx("span", { className: "vac-os-button-face", children: children }) }));
+}
+export function BookingLab({ stage, onStage, onFocusBooking, }) {
+    const { state, dispatch, trip } = useBookingLab();
+    const [selected, select] = useState(null);
+    const attempts = state.runs.filter((run) => run.outcome === state.lesson);
+    const run = attempts.find((run) => run.id === selected) ?? attempts.at(-1);
+    const success = state.lesson === "success";
+    function apply() {
+        dispatch({ type: "apply", source: "confirmation", outcome: state.lesson });
+        select(null);
+        onFocusBooking();
+    }
+    if (stage === 0)
+        return (_jsxs("div", { className: "vac-guide-intro", children: [_jsx("h3", { children: "Follow a booking from click to confirmation" }), _jsx("p", { children: "First, complete a successful booking and inspect its events. Then repeat the exercise with a failed request." }), _jsxs("div", { className: "vac-guide-example vac-booking-overview", children: [_jsx("strong", { children: "Book stay \u2192 Validate trip \u2192 Receive result" }), _jsx("p", { children: "Record the attempt on click. Record completion only after confirmation." })] }), _jsx(Action, { onClick: () => onStage(1), children: success
+                        ? "Practice a successful booking →"
+                        : "Continue the failure exercise →" })] }));
+    if (stage === 1 && state.applied) {
+        const { errors } = validateTrip(trip, Number.MAX_SAFE_INTEGER, todayAtStay());
+        const datesReady = !errors.checkIn && !errors.checkOut;
+        const guestsReady = !errors.guests;
+        const finished = !!state.latest;
+        const tasks = [
+            {
+                label: "Choose check-in and check-out dates",
+                done: datesReady || finished,
+            },
+            { label: "Choose your guests", done: guestsReady || finished },
+            {
+                label: (_jsxs(_Fragment, { children: ["Click ", _jsx("strong", { children: "Book stay" }), " on Twig"] })),
+                done: finished,
+            },
+        ];
+        const current = tasks.findIndex((task) => !task.done);
+        return (_jsxs("section", { className: "vac-lab vac-builder", children: [_jsx("h3", { children: finished
+                        ? success
+                            ? "Your booking is confirmed"
+                            : "Your booking request failed"
+                        : "Make your booking on Twig" }), _jsx("p", { role: "status", children: finished ? ("Your attempt is recorded. Next, review the events it produced.") : (_jsxs(_Fragment, { children: ["Code applied. Use the ", _jsx("strong", { children: "Your stay" }), " form on Twig to complete these steps."] })) }), _jsx("ol", { className: "vac-booking-checklist", "aria-label": "Booking progress", children: tasks.map((task, index) => (_jsxs("li", { "data-state": task.done ? "done" : index === current ? "current" : "upcoming", "aria-current": index === current ? "step" : undefined, children: [_jsx("span", { className: "vac-check-status", "aria-label": task.done
+                                    ? "Complete"
+                                    : index === current
+                                        ? "Next"
+                                        : "Upcoming", children: task.done ? "✓" : index + 1 }), _jsx("span", { children: task.label })] }, index))) }), finished ? (_jsx(Action, { onClick: () => onStage(2), children: success ? "Inspect the success →" : "Inspect the failure →" })) : (_jsx(Action, { onClick: onFocusBooking, children: "Show the booking form \u2192" })), _jsxs("details", { className: "vac-lab-step", children: [_jsx("summary", { children: "Applied code" }), _jsx("pre", { className: "vac-booking-code", children: bookingCode("confirmation") })] })] }));
+    }
+    if (stage === 1)
+        return (_jsxs("section", { className: "vac-lab vac-builder", children: [_jsx("h3", { children: state.latest
+                        ? success
+                            ? "Your booking is confirmed"
+                            : "Your booking request failed"
+                        : success
+                            ? "Make a successful booking"
+                            : "Try a failed booking" }), _jsx("p", { children: success ? (_jsxs(_Fragment, { children: ["This code records events from Twig\u2019s ", _jsx("strong", { children: "Book stay" }), " ", "button. Apply it, then make a simulated booking to see", " ", _jsx("code", { children: "booking_started" }), " on click and", " ", _jsx("code", { children: "booking_completed" }), " after confirmation."] })) : ("This request will fail. Keep the same code: it should record the attempt without recording a completed booking.") }), _jsx("pre", { className: "vac-booking-code", "aria-label": "Booking capture code", children: bookingCode("confirmation") }), _jsx(Action, { onClick: apply, children: "Apply the code \u2192" })] }));
+    if (!run)
+        return (_jsxs("div", { className: "vac-lab", children: [_jsx("h3", { children: success
+                        ? "Complete the successful booking first"
+                        : "Try the failed booking first" }), _jsx("p", { children: "Try this scenario on Twig, then inspect its events here." }), _jsx(Action, { onClick: () => onStage(1), children: "Continue the exercise \u2192" })] }));
+    const completed = run.events.some((event) => event.event === "booking_completed");
+    const mismatch = completed && run.outcome === "failure";
+    const before = state.runs.find((item) => item.source === "click" && item.outcome === "failure");
+    return (_jsxs("section", { className: "vac-lab vac-builder", children: [_jsx("h3", { children: success
+                    ? "What the successful booking recorded"
+                    : "What the failed booking recorded" }), attempts.length > 1 && (_jsx(LabChoices, { label: "Booking attempt", value: run.id, onChange: select, options: [...attempts].reverse().map((item) => ({
+                    value: item.id,
+                    label: (_jsxs(_Fragment, { children: [item.id, " \u00B7 ", item.outcome, " \u00B7", " ", item.source === "click" ? "on click" : "on confirmation"] })),
+                })) })), _jsxs("dl", { className: "vac-event-comparison", children: [_jsxs("div", { children: [_jsx("dt", { children: "Twig\u2019s result" }), _jsx("dd", { children: run.outcome === "success"
+                                    ? "Confirmed (simulation)"
+                                    : "Request failed" })] }), _jsxs("div", { "data-mismatch": mismatch, children: [_jsx("dt", { children: "Completion recorded" }), _jsx("dd", { children: completed ? "Yes" : "No" })] })] }), _jsx("p", { role: "status", children: mismatch
+                    ? "This completion is false. The click recorded it before the failed response arrived."
+                    : run.outcome === "failure"
+                        ? "Correct. The request failed, so no completion was recorded. The started event still shows the attempt."
+                        : run.source === "click"
+                            ? "These match this time, but the code recorded completion before the response. A failed request would still count as completed."
+                            : "Correct. Completion was recorded after the successful response." }), _jsx("h4", { children: "This attempt\u2019s funnel" }), _jsx("p", { className: "vac-muted", children: "A funnel tracks which steps were reached. These counts describe one local simulated attempt, not real visitors." }), _jsx("ol", { className: "vac-booking-funnel", children: ["availability_checked", "booking_started", "booking_completed"].map((name) => (_jsxs("li", { children: [_jsx("code", { children: name }), _jsx("strong", { children: run.events.some((event) => event.event === name) ? "1" : "0" })] }, name))) }), mismatch && (_jsx("p", { children: "The funnel reports a completed booking even though Twig rejected it. A chart can only be as accurate as the events you send." })), before && run.source === "confirmation" && run.outcome === "failure" && (_jsxs("div", { className: "vac-guide-example", children: [_jsx("strong", { children: "Same failure, different evidence" }), _jsx("p", { children: "Before: a completion on click. Now: an attempt, with no false completion." })] })), success ? (_jsxs(_Fragment, { children: [_jsx("p", { children: "The attempt and completion both appear because Twig confirmed the booking. Next, use the same code with a failed request." }), _jsx(Action, { onClick: () => {
+                            dispatch({ type: "begin-failure" });
+                            select(null);
+                            onStage(1);
+                        }, children: "Now practice a failed booking \u2192" })] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "vac-guide-example vac-booking-overview", children: [_jsx("strong", { children: "Same code, different result" }), _jsx("p", { children: "Success: started and completed. Failure: started only. The confirmation check keeps a failed request out of your completed-booking count." })] }), !mismatch && _jsx(FinishLabButton, { onClick: () => onStage(3) })] })), _jsxs("details", { className: "vac-lab-step", children: [_jsx("summary", { children: "Captured events and applied code" }), _jsx("p", { children: "Availability is recorded when the local availability check succeeds. Start records the request. Completion depends on the code you applied." }), _jsx("pre", { className: "vac-booking-code", children: bookingCode(run.source) }), _jsx("pre", { children: JSON.stringify(run.events, null, 2) })] })] }));
+}

package/dist/BrowseStaysPreview.d.ts

@@ -0,0 +1,7 @@
+import { type StaySetting } from "./settings.js";
+export type BrowseStaysPreviewProps = {
+    selected: Exclude<StaySetting, "All">;
+    className?: string;
+};
+/** A read-only excerpt of Twig's Browse stays view for editorial contexts. */
+export declare function BrowseStaysPreview({ selected, className, }: BrowseStaysPreviewProps): import("react").JSX.Element;

package/dist/BrowseStaysPreview.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { staySettings } from "./settings.js";
+/** A read-only excerpt of Twig's Browse stays view for editorial contexts. */
+export function BrowseStaysPreview({ selected, className = "", }) {
+    return (_jsx("div", { className: `twig-stays-preview ${className}`.trim(), role: "img", "aria-label": `Twig Browse stays with the ${selected} filter selected and one ${selected} stay`, children: _jsxs("div", { className: "twig-stays-preview-inner", children: [_jsx("span", { className: "twig-stays-preview-kicker", children: "Explore" }), _jsx("h3", { children: "Browse stays" }), _jsx("div", { className: "twig-stays-preview-filters", "aria-hidden": "true", children: staySettings.map((setting) => (_jsx("span", { className: "twig-stays-preview-filter", "data-twig-filter": setting, "data-selected": setting === selected, children: setting === "All" ? "All stays" : setting }, setting))) }), _jsx("p", { className: "twig-stays-preview-count", children: "1 stay" }), _jsxs("div", { className: "twig-stays-preview-stay", children: [_jsx("span", { className: "twig-stays-preview-image", "aria-hidden": "true" }), _jsxs("span", { "data-twig-stay": selected, children: [selected, " stay"] })] })] }) }));
+}

package/dist/FilterInspector.d.ts

@@ -0,0 +1,7 @@
+import { type LabState } from "./filter-lab.js";
+export declare function FilterInspector({ state, onPractice, filterHref, bounded, }: {
+    state: LabState;
+    bounded?: boolean;
+    onPractice: () => void;
+    filterHref: string;
+}): import("react").JSX.Element;

package/dist/FilterInspector.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useId, useState } from "react";
+import { summarizeFilterEvents, } from "./filter-lab.js";
+export function FilterInspector({ state, onPractice, filterHref, bounded = false, }) {
+    const detailId = useId();
+    const [selection, setSelection] = useState(null);
+    const selected = selection && state.events.includes(selection)
+        ? selection
+        : state.events.at(-1);
+    const summary = summarizeFilterEvents(state.events);
+    const applied = state.applied;
+    if (!applied)
+        return (_jsxs("div", { className: "vac-lab-output", children: [_jsx("p", { children: "Apply your event in the exercise first. Then click Forest and Coast to compare their events here." }), _jsx("button", { className: "vac-button", onClick: onPractice, children: _jsx("span", { className: "vac-os-button-face", children: "Continue the exercise \u2192" }) })] }));
+    if (!selected)
+        return (_jsxs("div", { className: "vac-lab-output", children: [_jsx("h4", { children: "No events yet" }), _jsx("p", { children: "Click Forest, then Coast to compare their events." }), _jsx("a", { className: "vac-browse-link", href: filterHref, children: "Go to the filters \u2197" })] }));
+    const matches = selected.clicked === selected.properties.destination_type;
+    return (_jsxs(_Fragment, { children: [_jsxs("p", { className: "vac-muted", role: "status", children: [state.events.length, " local events \u00B7 ", summary.mismatches, " ", summary.mismatches === 1 ? "mismatch" : "mismatches"] }), _jsxs("div", { className: "vac-filter-comparisons", role: "group", "aria-label": "Recorded clicks", children: [_jsxs("div", { className: "vac-filter-comparison-head", "aria-hidden": "true", children: [_jsx("span", { children: "Clicked" }), _jsx("span", { children: "Recorded" }), _jsx("span", { children: "Result" })] }), _jsx("div", { className: "vac-filter-comparison-list", children: state.events.map((event) => {
+                            const match = event.clicked === event.properties.destination_type;
+                            return (_jsxs("button", { type: "button", className: "vac-filter-comparison-row", "aria-pressed": selected.id === event.id, "aria-controls": detailId, "aria-label": `Event ${event.id}: clicked ${event.clicked}, recorded ${event.properties.destination_type}, ${match ? "match" : "mismatch"}`, onClick: () => setSelection(event), children: [_jsxs("span", { children: [_jsxs("small", { children: ["#", event.id] }), " ", event.clicked] }), _jsx("code", { children: event.properties.destination_type }), _jsx("span", { className: "vac-filter-match", "data-mismatch": !match, children: match ? "Match" : "Mismatch" })] }, event.id));
+                        }) })] }), _jsxs("section", { id: detailId, className: "vac-lab-output", "aria-label": `Event ${selected.id} comparison`, children: [_jsxs("h4", { children: ["Event #", selected.id] }), _jsx("code", { className: "vac-inspect-name", children: selected.event }), _jsxs("dl", { className: "vac-event-comparison", children: [_jsxs("div", { children: [_jsx("dt", { children: "Clicked on Twig" }), _jsx("dd", { children: selected.clicked })] }), _jsxs("div", { "data-mismatch": !matches, children: [_jsx("dt", { children: "Recorded destination type" }), _jsx("dd", { children: selected.properties.destination_type })] })] }), _jsx("p", { children: matches
+                            ? "These values match."
+                            : "Mismatch: the event describes a different filter from the one clicked." }), _jsx("p", { className: "vac-muted", children: applied.source === "fixed"
+                            ? `The source is a fixed value: ${applied.fixedValue}. Every click records that value, even when a different filter is selected.`
+                            : "The value comes from the clicked filter, so it changes with the interaction." })] }), state.before.some((event) => event.clicked === selected.clicked) && (_jsxs("div", { className: "vac-ai-compare", children: [_jsx("h4", { children: "Same click, different instrumentation" }), _jsxs("dl", { children: [_jsx("dt", { children: "Before \u00B7 fixed value" }), _jsxs("dd", { children: [selected.clicked, " \u2192", " ", state.before.find((event) => event.clicked === selected.clicked)
+                                        ?.properties.destination_type] }), _jsxs("dt", { children: ["Now \u00B7", " ", applied.source === "clicked" ? "clicked value" : "fixed value"] }), _jsxs("dd", { children: [selected.clicked, " \u2192 ", selected.properties.destination_type] })] })] })), !bounded && applied.source === "fixed" && (_jsx("button", { className: "vac-button", onClick: onPractice, children: _jsx("span", { className: "vac-os-button-face", children: "Connect the clicked value \u2192" }) }))] }));
+}

package/dist/FilterLabExercise.d.ts

@@ -0,0 +1,14 @@
+import { type LabAction, type LabState } from "./filter-lab.js";
+export declare function FilterLabIntroduction({ onContinue }: {
+    onContinue: () => void;
+}): import("react").JSX.Element;
+export declare function FilterLabExercise({ state, dispatch, stage, setStage, embedSource, onFocusFilters, onContinue, filterHref, }: {
+    state: LabState;
+    dispatch: (action: LabAction) => void;
+    stage: number;
+    setStage: (stage: number) => void;
+    embedSource?: "fixed" | "clicked";
+    onFocusFilters: () => void;
+    onContinue: (source: "fixed" | "clicked") => void;
+    filterHref: string;
+}): import("react").JSX.Element;

package/dist/FilterLabExercise.js

@@ -0,0 +1,78 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { LabChoices } from "./LabChoices.js";
+import { LabChecklist } from "./LabChecklist.js";
+import { FilterInspector } from "./FilterInspector.js";
+import { filterLabCode, labPassed } from "./filter-lab.js";
+import { useId } from "react";
+export function FilterLabIntroduction({ onContinue }) {
+    return (_jsxs("div", { className: "vac-guide-intro", children: [_jsx("h3", { children: "Why does every click look like Forest?" }), _jsx("p", { children: "Visitors choose different filters, but your events keep recording Forest." }), _jsx("div", { className: "vac-guide-example vac-guide-lesson", children: _jsx("p", { children: "Follow a click into its event, find the fixed value, then connect the filter\u2019s actual value." }) }), _jsx("p", { children: "The goal: record which destination type each visitor chose." }), _jsx("button", { className: "vac-button", onClick: onContinue, children: _jsx("span", { className: "vac-os-button-face", children: "See the worked example \u2192" }) }), _jsxs("details", { className: "vac-lab-step", children: [_jsx("summary", { children: "How this simulation works" }), _jsx("p", { children: "After you apply your configuration, this lab records filter clicks locally while the exercise is open. Nothing is sent to PostHog." }), _jsx("p", { children: "Returning to the list pauses recording and keeps your work. Leaving the page resets it." })] })] }));
+}
+function FilterCode({ config }) {
+    return (_jsxs("pre", { children: [`// Inside the filter's click handler\nposthog.capture(${JSON.stringify(config.eventName)}, {\n`, _jsx("mark", { className: "vac-ai-code-highlight", children: `  destination_type: ${config.source === "clicked"
+                    ? "selectedDestinationType"
+                    : JSON.stringify(config.fixedValue)},` }), "\n});"] }));
+}
+export function FilterLabExercise({ state, dispatch, stage, setStage, embedSource, onFocusFilters, onContinue, filterHref, }) {
+    const titleId = useId();
+    const latest = state.events.at(-1);
+    const passed = labPassed(state);
+    const example = {
+        eventName: "stay_filter_selected",
+        source: "fixed",
+        fixedValue: "Forest",
+    };
+    const triedBoth = ["Forest", "Coast"].every((setting) => state.events.some((event) => event.clicked === setting));
+    const nextFilter = state.events.some((event) => event.clicked === "Forest")
+        ? "Coast"
+        : "Forest";
+    return (_jsxs("section", { className: "vac-lab vac-builder", "aria-labelledby": titleId, children: [_jsx("h3", { id: titleId, children: stage === 2
+                    ? "Compare the click with the event"
+                    : state.step === 0
+                        ? "From a filter click to an event"
+                        : state.step === 2
+                            ? "Connect the clicked value"
+                            : triedBoth
+                                ? "Now compare the evidence"
+                                : `Try ${nextFilter} on Twig` }), stage === 1 && (_jsxs(_Fragment, { children: [state.step === 0 && (_jsxs(_Fragment, { children: [_jsxs("p", { children: ["When someone clicks a filter, its click handler runs this code. The event name describes the action \u2013", " ", _jsx("code", { children: "destination_type" }), " records which filter it was."] }), _jsx(FilterCode, { config: { ...example, source: embedSource ?? example.source } }), embedSource === "clicked" ? (_jsxs("p", { children: ["The property now reads ", _jsx("code", { children: "selectedDestinationType" }), " ", "from each click. Apply the code, then test", " ", _jsx("strong", { children: "Forest" }), " and ", _jsx("strong", { children: "Coast" }), "."] })) : (_jsxs("p", { children: [_jsx("code", { children: '"Forest"' }), " is a fixed value. First, click", " ", _jsx("strong", { children: "Forest" }), " to see how it becomes an event. Then try ", _jsx("strong", { children: "Coast" }), "."] })), _jsx("button", { className: "vac-button", onClick: () => {
+                                    dispatch({ type: "example" });
+                                    if (embedSource === "clicked") {
+                                        dispatch({ type: "edit", config: { source: "clicked" } });
+                                        dispatch({ type: "apply" });
+                                    }
+                                    onFocusFilters();
+                                }, children: _jsx("span", { className: "vac-os-button-face", children: "Apply the code \u2192" }) })] })), state.step === 2 && (_jsxs(_Fragment, { children: [_jsxs("p", { children: ["Twig stores the clicked filter in", " ", _jsx("code", { children: "selectedDestinationType" }), ". Use that value instead of the text ", _jsx("code", { children: '"Forest"' }), "."] }), _jsx(LabChoices, { label: _jsxs(_Fragment, { children: ["Where should ", _jsx("code", { children: "destination_type" }), " come from?"] }), value: state.config.source, onChange: (source) => dispatch({ type: "edit", config: { source } }), options: [
+                                    {
+                                        value: "fixed",
+                                        label: (_jsxs(_Fragment, { children: ["Fixed text: ", _jsx("code", { children: '"Forest"' })] })),
+                                    },
+                                    {
+                                        value: "clicked",
+                                        label: (_jsxs(_Fragment, { children: ["The clicked filter: ", _jsx("code", { children: "selectedDestinationType" })] })),
+                                    },
+                                ] }), _jsx(FilterCode, { config: state.config }), _jsx("p", { className: "vac-muted", children: state.config.source === "clicked"
+                                    ? "The highlighted line now reads the value from each click."
+                                    : "This still records Forest for every click." }), _jsx("button", { className: "vac-button", onClick: () => {
+                                    dispatch({ type: "apply" });
+                                    onFocusFilters();
+                                }, children: _jsx("span", { className: "vac-os-button-face", children: "Apply the change \u2192" }) })] })), state.step === 3 && (_jsxs(_Fragment, { children: [_jsx("p", { children: triedBoth ? ("You’ve clicked both filters. Inspect how those clicks were recorded.") : (_jsxs(_Fragment, { children: ["Click ", _jsx("strong", { children: nextFilter }), " in Twig\u2019s stay filters. Watch the event below update."] })) }), _jsx(LabChecklist, { label: "Filter exercise progress", items: [
+                                    {
+                                        label: (_jsxs(_Fragment, { children: ["Click ", _jsx("strong", { children: "Forest" }), " on Twig"] })),
+                                        done: state.events.some((event) => event.clicked === "Forest"),
+                                    },
+                                    {
+                                        label: (_jsxs(_Fragment, { children: ["Click ", _jsx("strong", { children: "Coast" }), " on Twig"] })),
+                                        done: state.events.some((event) => event.clicked === "Coast"),
+                                    },
+                                ] }), latest && (_jsxs("p", { role: "status", children: ["Last click: ", _jsx("strong", { children: latest.clicked }), ". Recorded", " ", _jsx("code", { children: "destination_type" }), ":", " ", _jsx("code", { children: latest.properties.destination_type }), "."] })), triedBoth ? (_jsx("button", { className: "vac-button", onClick: () => setStage(2), children: _jsx("span", { className: "vac-os-button-face", children: "Inspect the difference \u2192" }) })) : (_jsx("button", { className: "vac-button", onClick: onFocusFilters, children: _jsx("span", { className: "vac-os-button-face", children: "Go to the filters \u2192" }) }))] }))] })), stage === 2 && (_jsx(FilterInspector, { state: state, filterHref: filterHref, bounded: Boolean(embedSource), onPractice: () => {
+                    if (state.selected)
+                        dispatch({ type: "repair" });
+                    setStage(1);
+                } })), embedSource && stage === 2 && triedBoth && (_jsxs("div", { className: "vac-lab-output", children: [_jsx("h4", { children: embedSource === "fixed"
+                            ? "The mismatch is visible"
+                            : "The values match" }), _jsx("p", { children: embedSource === "fixed"
+                            ? "Continue reading to see how the team fixes this."
+                            : "Continue reading to see what the team can now measure." }), _jsx("button", { className: "vac-button", onClick: () => onContinue(embedSource), children: _jsx("span", { className: "vac-os-button-face", children: "Continue reading \u2192" }) })] })), !embedSource && passed && stage === 2 && (_jsx("button", { type: "button", className: "vac-button", onClick: () => setStage(3), children: _jsx("span", { className: "vac-os-button-face", children: "Finish lab" }) })), stage === 1 && state.events.length >= 20 && (_jsx("p", { children: "20-event limit reached. Clear the run to continue." })), stage === 1 && (_jsxs("details", { className: "vac-lab-step", children: [_jsx("summary", { children: "Code and session options" }), _jsx("pre", { children: filterLabCode(embedSource && state.step === 0
+                            ? { ...example, source: embedSource }
+                            : state.applied ?? state.config) }), _jsx("div", { className: "vac-lab-actions", children: state.events.length > 0 && (_jsx("button", { className: "vac-text-button", onClick: () => dispatch({ type: "clear" }), children: "Clear events" })) })] }))] }));
+}

package/dist/FinishLabButton.d.ts

@@ -0,0 +1,3 @@
+export declare function FinishLabButton({ onClick }: {
+    onClick: () => void;
+}): import("react").JSX.Element;

package/dist/FinishLabButton.js

@@ -0,0 +1,5 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+export function FinishLabButton({ onClick }) {
+    return (_jsx("button", { type: "button", className: "vac-button", onClick: onClick, children: _jsx("span", { className: "vac-os-button-face", children: "Finish lab" }) }));
+}

package/dist/LabChecklist.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+export declare function LabChecklist({ label, items, }: {
+    label: string;
+    items: {
+        label: ReactNode;
+        done: boolean;
+    }[];
+}): import("react").JSX.Element;

package/dist/LabChecklist.js

@@ -0,0 +1,6 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function LabChecklist({ label, items, }) {
+    const current = items.findIndex((item) => !item.done);
+    return (_jsx("ol", { className: "vac-booking-checklist", "aria-label": label, children: items.map((item, index) => (_jsxs("li", { "data-state": item.done ? "done" : index === current ? "current" : "upcoming", "aria-current": index === current ? "step" : undefined, children: [_jsx("span", { className: "vac-check-status", "aria-label": item.done ? "Complete" : index === current ? "Next" : "Upcoming", children: item.done ? "✓" : index + 1 }), _jsx("span", { children: item.label })] }, index))) }));
+}