@posthog/twig-components 0.1.0

package/dist/playground.d.ts

@@ -0,0 +1,167 @@
+/** Stable IDs identify instrumentation; displayed marker numbers are page-local. */
+export declare const touchpointDefinitions: {
+    readonly discovery: {
+        readonly title: "AI trip discovery";
+        readonly color: "yellow";
+        readonly tool: "AI observability";
+        readonly lesson: "Inspect a trip-planning request and its model response.";
+        readonly lab: "ai-discovery";
+        readonly description: "Configure AI observability fields, then test a simulated recommendation or timeout.";
+        readonly evidence: "Local generation events only; no model or PostHog connection.";
+    };
+    readonly catalog: {
+        readonly title: "Stay filters";
+        readonly color: "blue";
+        readonly tool: "Product analytics";
+        readonly lesson: "Capture filter clicks and attach the selected setting.";
+        readonly lab: "filter-events";
+        readonly description: "Setting filters narrow the catalog. Select a stay to see its details and nightly rate.";
+        readonly evidence: "No analytics capture connected.";
+    };
+    readonly replay: {
+        readonly title: "Follow a visitor";
+        readonly color: "red";
+        readonly tool: "Session Replay";
+        readonly lesson: "Watch a ghost visit, then record and inspect your own interactions.";
+        readonly lab: "session-replay";
+        readonly description: "Explore interaction sequences and input masking.";
+        readonly evidence: "Local interaction reconstruction; no PostHog recording.";
+    };
+    readonly stay: {
+        readonly title: "Stay details";
+        readonly color: "blue";
+        readonly tool: "Product analytics";
+        readonly lesson: "Connect a stay’s ID to its view event.";
+        readonly lab: "stay-views";
+        readonly description: "This page reads the selected stay’s catalog entry and host profile. Photos, amenities, and prices belong to this stay.";
+        readonly evidence: "Locally simulated view events from navigation between stay pages.";
+    };
+    readonly booking: {
+        readonly title: "Booking";
+        readonly color: "yellow";
+        readonly tool: "Product analytics";
+        readonly lesson: "Record a completed booking only after confirmation.";
+        readonly lab: "booking-events";
+        readonly description: "Compare a failed booking with its captured events, then move completion capture to the successful response.";
+        readonly evidence: "Local simulated availability and booking responses. No reservation or payment created.";
+    };
+};
+export type TouchpointId = keyof typeof touchpointDefinitions;
+type PageKind = "discover" | "stay" | "about";
+export declare function playgroundPage(pathname: string, catalog: readonly {
+    id: string;
+    title: string | null;
+}[]): {
+    key: string;
+    kind: PageKind | null;
+    stayId: string | null;
+    label: string;
+    touchpoints: ({
+        title: "AI trip discovery";
+        color: "yellow";
+        tool: "AI observability";
+        lesson: "Inspect a trip-planning request and its model response.";
+        lab: "ai-discovery";
+        description: "Configure AI observability fields, then test a simulated recommendation or timeout.";
+        evidence: "Local generation events only; no model or PostHog connection.";
+        id: "stay" | "discovery" | "catalog" | "replay" | "booking";
+        number: number;
+    } | {
+        title: "Stay filters";
+        color: "blue";
+        tool: "Product analytics";
+        lesson: "Capture filter clicks and attach the selected setting.";
+        lab: "filter-events";
+        description: "Setting filters narrow the catalog. Select a stay to see its details and nightly rate.";
+        evidence: "No analytics capture connected.";
+        id: "stay" | "discovery" | "catalog" | "replay" | "booking";
+        number: number;
+    } | {
+        title: "Follow a visitor";
+        color: "red";
+        tool: "Session Replay";
+        lesson: "Watch a ghost visit, then record and inspect your own interactions.";
+        lab: "session-replay";
+        description: "Explore interaction sequences and input masking.";
+        evidence: "Local interaction reconstruction; no PostHog recording.";
+        id: "stay" | "discovery" | "catalog" | "replay" | "booking";
+        number: number;
+    } | {
+        title: "Stay details";
+        color: "blue";
+        tool: "Product analytics";
+        lesson: "Connect a stay’s ID to its view event.";
+        lab: "stay-views";
+        description: "This page reads the selected stay’s catalog entry and host profile. Photos, amenities, and prices belong to this stay.";
+        evidence: "Locally simulated view events from navigation between stay pages.";
+        id: "stay" | "discovery" | "catalog" | "replay" | "booking";
+        number: number;
+    } | {
+        title: "Booking";
+        color: "yellow";
+        tool: "Product analytics";
+        lesson: "Record a completed booking only after confirmation.";
+        lab: "booking-events";
+        description: "Compare a failed booking with its captured events, then move completion capture to the successful response.";
+        evidence: "Local simulated availability and booking responses. No reservation or payment created.";
+        id: "stay" | "discovery" | "catalog" | "replay" | "booking";
+        number: number;
+    })[];
+};
+export type PlaygroundPage = ReturnType<typeof playgroundPage>;
+export type PlaygroundSelection = {
+    pageKey: string;
+    id: TouchpointId;
+};
+export declare function selectedTouchpoint(page: PlaygroundPage, selection: PlaygroundSelection | null): {
+    title: "AI trip discovery";
+    color: "yellow";
+    tool: "AI observability";
+    lesson: "Inspect a trip-planning request and its model response.";
+    lab: "ai-discovery";
+    description: "Configure AI observability fields, then test a simulated recommendation or timeout.";
+    evidence: "Local generation events only; no model or PostHog connection.";
+    id: "stay" | "discovery" | "catalog" | "replay" | "booking";
+    number: number;
+} | {
+    title: "Stay filters";
+    color: "blue";
+    tool: "Product analytics";
+    lesson: "Capture filter clicks and attach the selected setting.";
+    lab: "filter-events";
+    description: "Setting filters narrow the catalog. Select a stay to see its details and nightly rate.";
+    evidence: "No analytics capture connected.";
+    id: "stay" | "discovery" | "catalog" | "replay" | "booking";
+    number: number;
+} | {
+    title: "Follow a visitor";
+    color: "red";
+    tool: "Session Replay";
+    lesson: "Watch a ghost visit, then record and inspect your own interactions.";
+    lab: "session-replay";
+    description: "Explore interaction sequences and input masking.";
+    evidence: "Local interaction reconstruction; no PostHog recording.";
+    id: "stay" | "discovery" | "catalog" | "replay" | "booking";
+    number: number;
+} | {
+    title: "Stay details";
+    color: "blue";
+    tool: "Product analytics";
+    lesson: "Connect a stay’s ID to its view event.";
+    lab: "stay-views";
+    description: "This page reads the selected stay’s catalog entry and host profile. Photos, amenities, and prices belong to this stay.";
+    evidence: "Locally simulated view events from navigation between stay pages.";
+    id: "stay" | "discovery" | "catalog" | "replay" | "booking";
+    number: number;
+} | {
+    title: "Booking";
+    color: "yellow";
+    tool: "Product analytics";
+    lesson: "Record a completed booking only after confirmation.";
+    lab: "booking-events";
+    description: "Compare a failed booking with its captured events, then move completion capture to the successful response.";
+    evidence: "Local simulated availability and booking responses. No reservation or payment created.";
+    id: "stay" | "discovery" | "catalog" | "replay" | "booking";
+    number: number;
+};
+export {};

package/dist/playground.js

@@ -0,0 +1,91 @@
+/** Stable IDs identify instrumentation; displayed marker numbers are page-local. */
+export const touchpointDefinitions = {
+    discovery: {
+        title: "AI trip discovery",
+        color: "yellow",
+        tool: "AI observability",
+        lesson: "Inspect a trip-planning request and its model response.",
+        lab: "ai-discovery",
+        description: "Configure AI observability fields, then test a simulated recommendation or timeout.",
+        evidence: "Local generation events only; no model or PostHog connection.",
+    },
+    catalog: {
+        title: "Stay filters",
+        color: "blue",
+        tool: "Product analytics",
+        lesson: "Capture filter clicks and attach the selected setting.",
+        lab: "filter-events",
+        description: "Setting filters narrow the catalog. Select a stay to see its details and nightly rate.",
+        evidence: "No analytics capture connected.",
+    },
+    replay: {
+        title: "Follow a visitor",
+        color: "red",
+        tool: "Session Replay",
+        lesson: "Watch a ghost visit, then record and inspect your own interactions.",
+        lab: "session-replay",
+        description: "Explore interaction sequences and input masking.",
+        evidence: "Local interaction reconstruction; no PostHog recording.",
+    },
+    stay: {
+        title: "Stay details",
+        color: "blue",
+        tool: "Product analytics",
+        lesson: "Connect a stay’s ID to its view event.",
+        lab: "stay-views",
+        description: "This page reads the selected stay’s catalog entry and host profile. Photos, amenities, and prices belong to this stay.",
+        evidence: "Locally simulated view events from navigation between stay pages.",
+    },
+    booking: {
+        title: "Booking",
+        color: "yellow",
+        tool: "Product analytics",
+        lesson: "Record a completed booking only after confirmation.",
+        lab: "booking-events",
+        description: "Compare a failed booking with its captured events, then move completion capture to the successful response.",
+        evidence: "Local simulated availability and booking responses. No reservation or payment created.",
+    },
+};
+const pageTouchpoints = {
+    discover: ["discovery", "catalog", "replay"],
+    about: [],
+    stay: ["stay", "booking", "replay"],
+};
+export function playgroundPage(pathname, catalog) {
+    const path = pathname.replace(/\/+$/, "") || "/";
+    const match = /^\/stays\/([^/]+)$/.exec(path);
+    const stay = match
+        ? catalog.find((entry) => entry.id === match[1])
+        : undefined;
+    const kind = path === "/"
+        ? "discover"
+        : path === "/about"
+            ? "about"
+            : stay
+                ? "stay"
+                : null;
+    const ids = kind ? pageTouchpoints[kind] : [];
+    return {
+        key: path,
+        kind,
+        stayId: stay?.id ?? null,
+        label: kind === "discover"
+            ? "Find a stay"
+            : kind === "about"
+                ? "About Twig"
+                : stay
+                    ? `Stay details${stay.title ? ` · ${stay.title}` : ""}`
+                    : "This page",
+        touchpoints: ids.map((id, index) => ({
+            id,
+            number: index + 1,
+            ...touchpointDefinitions[id],
+        })),
+    };
+}
+export function selectedTouchpoint(page, selection) {
+    return ((selection?.pageKey === page.key &&
+        page.touchpoints.find((item) => item.id === selection.id)) ||
+        page.touchpoints[0] ||
+        null);
+}

package/dist/replay-lab.d.ts

@@ -0,0 +1,19 @@
+export type ReplayFrame = {
+    at: number;
+    kind: "move" | "click" | "input" | "page" | "scroll" | "state";
+    page: string;
+    label: string;
+    x?: number;
+    y?: number;
+    value?: string;
+};
+export declare const REPLAY_LIMIT = 500;
+export declare function replayPage(path: string): boolean;
+export declare function searchValue(value: string, masked: boolean): string;
+export declare function replayScene(frames: ReplayFrame[], index: number): {
+    page: string;
+    filter: string;
+    search: string;
+    x: number;
+    y: number;
+};

package/dist/replay-lab.js

@@ -0,0 +1,26 @@
+export const REPLAY_LIMIT = 500;
+export function replayPage(path) {
+    return path === "/" || /^\/stays\/[^/?#]+$/.test(path);
+}
+export function searchValue(value, masked) {
+    return masked ? "[masked]" : value.slice(0, 80);
+}
+export function replayScene(frames, index) {
+    let page = "/", filter = "All", search = "", x = 50, y = 30;
+    for (const frame of frames.slice(0, index + 1)) {
+        if (frame.page !== page) {
+            page = frame.page;
+            filter = "All";
+            search = "";
+        }
+        if (frame.label.startsWith("Filter: "))
+            filter = frame.label.slice(8);
+        if (frame.kind === "input")
+            search = frame.value ?? "";
+        if (frame.x !== undefined)
+            x = frame.x;
+        if (frame.y !== undefined)
+            y = frame.y;
+    }
+    return { page, filter, search, x, y };
+}

package/dist/settings.d.ts

@@ -0,0 +1,2 @@
+export declare const staySettings: readonly ["All", "Forest", "Coast", "Mountain"];
+export type StaySetting = (typeof staySettings)[number];

package/dist/settings.js

@@ -0,0 +1 @@
+export const staySettings = ["All", "Forest", "Coast", "Mountain"];

package/dist/stay-lab.d.ts

@@ -0,0 +1,32 @@
+export type StayView = {
+    actualStayId: string;
+    actualTitle: string;
+    event: "stay_viewed";
+    properties: {
+        stay_id?: string;
+    };
+};
+export type StayLabState = {
+    applied: "anonymous" | "identified" | null;
+    running: boolean;
+    events: StayView[];
+    before: StayView[];
+    revision: number;
+};
+export declare const initialStayLab: StayLabState;
+export type StayLabAction = {
+    type: "reset";
+} | {
+    type: "pause";
+} | {
+    type: "apply";
+    identified: boolean;
+} | {
+    type: "repair";
+} | {
+    type: "view";
+    id: string;
+    title: string;
+};
+export declare function stayLabReducer(state: StayLabState, action: StayLabAction): StayLabState;
+export declare function stayCode(identified: boolean): "posthog.capture(\"stay_viewed\", {\n  stay_id: stay.id\n});" | "posthog.capture(\"stay_viewed\");";

package/dist/stay-lab.js

@@ -0,0 +1,53 @@
+export const initialStayLab = {
+    applied: null,
+    running: false,
+    events: [],
+    before: [],
+    revision: 0,
+};
+export function stayLabReducer(state, action) {
+    switch (action.type) {
+        case "reset":
+            return { ...initialStayLab, revision: state.revision + 1 };
+        case "pause":
+            return { ...state, running: false };
+        case "apply":
+            return {
+                ...state,
+                applied: action.identified ? "identified" : "anonymous",
+                running: true,
+                events: [],
+            };
+        case "repair":
+            return {
+                ...state,
+                before: state.events,
+                events: [],
+                applied: null,
+                running: false,
+            };
+        case "view":
+            return !state.running ||
+                !state.applied ||
+                !action.id ||
+                state.events.length >= 20
+                ? state
+                : {
+                    ...state,
+                    events: [
+                        ...state.events,
+                        {
+                            actualStayId: action.id,
+                            actualTitle: action.title,
+                            event: "stay_viewed",
+                            properties: state.applied === "identified" ? { stay_id: action.id } : {},
+                        },
+                    ],
+                };
+    }
+}
+export function stayCode(identified) {
+    return identified
+        ? 'posthog.capture("stay_viewed", {\n  stay_id: stay.id\n});'
+        : 'posthog.capture("stay_viewed");';
+}

package/dist/trip-dates.d.ts

@@ -0,0 +1,11 @@
+export type TripSelection = {
+    checkIn: string;
+    checkOut: string;
+    guests: string;
+};
+export type TripErrors = Partial<Record<keyof TripSelection, string>>;
+export declare function todayAtStay(now?: Date): string;
+export declare function validateTrip(selection: TripSelection, capacity: number, today: string): {
+    errors: Partial<Record<keyof TripSelection, string>>;
+    nights: number | null;
+};

package/dist/trip-dates.js

@@ -0,0 +1,49 @@
+const DAY_MS = 86_400_000;
+/** Calendar dates are UTC day numbers, not instants in the guest's timezone. */
+function calendarDay(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return null;
+    const timestamp = Date.parse(`${value}T00:00:00Z`);
+    if (!Number.isFinite(timestamp))
+        return null;
+    if (new Date(timestamp).toISOString().slice(0, 10) !== value)
+        return null;
+    return timestamp / DAY_MS;
+}
+export function todayAtStay(now = new Date()) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone: "America/New_York",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).formatToParts(now);
+    const part = (type) => parts.find((entry) => entry.type === type).value;
+    return `${part("year")}-${part("month")}-${part("day")}`;
+}
+export function validateTrip(selection, capacity, today) {
+    const errors = {};
+    const start = calendarDay(selection.checkIn);
+    const end = calendarDay(selection.checkOut);
+    const current = calendarDay(today);
+    if (current === null)
+        throw new Error("A valid current date is required.");
+    if (start === null)
+        errors.checkIn = "Choose a valid check-in date.";
+    else if (start < current)
+        errors.checkIn = "Check-in can’t be in the past.";
+    if (end === null)
+        errors.checkOut = "Choose a valid check-out date.";
+    else if (start !== null && end <= start)
+        errors.checkOut = "Check-out must be after check-in.";
+    const guests = Number(selection.guests);
+    if (!/^\d+$/.test(selection.guests) ||
+        !Number.isInteger(guests) ||
+        guests < 1 ||
+        guests > capacity) {
+        errors.guests = `Choose between 1 and ${capacity} guests.`;
+    }
+    return {
+        errors,
+        nights: start !== null && end !== null && end > start ? end - start : null,
+    };
+}

package/docs/components.md

@@ -0,0 +1,78 @@
+# Component reference
+
+Import only the pieces you need from `@posthog/twig-components/<path>`. React is a peer dependency: the host supplies React 18 or 19. Import `catalog.css` for Twig views and `lab.css` for the playground. See [integration](integration.md) for styling and update boundaries.
+
+“Used in Twig” below means the local workspace copy in `twig.com`; the standalone npm package is not published or installed yet. PostHog 101 does not currently import this package.
+
+## Website views and data
+
+| Import path | Export | What it does | Used in Twig / what the host supplies |
+| --- | --- | --- | --- |
+| `/filters` | `StayFilters`, `staySettings`, `StaySetting` | Controlled Forest/Coast/Mountain filter buttons; calls `onChange` on a click. | `Discover`; pass `value`, `onChange`, and optional CSS classes. The host filters the listings. |
+| `/stay-card` | `StayCardContent` | Listing text, location, capacity, and nightly price. | `StayCard`; pass a `stay` and `image`. The host supplies the link or card wrapper; `linked` shows an arrow. |
+| `/browse-stays-preview` | `BrowseStaysPreview` | Read-only Browse stays excerpt with one selected filter and stay. | Gallery only; intended for PostHog 101. Pass `selected="Forest"`, `"Coast"`, or `"Mountain"`. No click handler or analytics. |
+| `/catalog` | `stays`, `characters`, `conciergeContent`, `discoveryCopy`, `filterStays`, `stayLabel`, `nightlyPrice`, types | Fictional catalog content and pure display/filter helpers. | Discover, stay pages, and lab fixtures; the host supplies page layout and navigation. |
+| `/trip-dates` | `todayAtStay`, `validateTrip`, types | Date and guest validation for the booking exercise. | Booking flow; pass the visitor’s trip selection. |
+
+```tsx
+import { useState } from "react";
+import { StayFilters, type StaySetting } from "@posthog/twig-components/filters";
+import { filterStays } from "@posthog/twig-components/catalog";
+import "@posthog/twig-components/catalog.css";
+
+function Browse() {
+  const [setting, setSetting] = useState<StaySetting>("All");
+  return <>
+    <StayFilters
+      value={setting}
+      onChange={setSetting}
+      className="vac-filters"
+      buttonClassName="vac-filter"
+    />
+    <p>{filterStays(setting).length} stays</p>
+  </>;
+}
+```
+
+## Labs and playground
+
+These are **local teaching simulations**. They do not send events to PostHog, make bookings, or run an AI model. Twig.com supplies routes, page content, focus/scroll actions, and navigation callbacks.
+
+| Import path | Main exports | What it does / host input | Used in Twig |
+| --- | --- | --- | --- |
+| `/playground` | `playgroundPage`, `selectedTouchpoint`, `touchpointDefinitions`, types | Maps a Twig path and catalog to available lab markers; host passes the current path. | Playground and site adapters |
+| `/playground-controller` | `PlaygroundLabProvider`, `usePlaygroundLab`, `useFilterLab` | Owns selected lab, stage, and filter state; wrap the playground and pass `active` and `bookingEnabled`. Requires `ReplayProvider` and `StayLabProvider` above it. | Playground / FilterLab |
+| `/playground-panels` | `LabDirectory`, `SelectedLabHeader`, `PlaygroundMarker`, `PlaygroundInvitation`, `PlaygroundDock` | Lab list, page markers, invitation, and dock layout; host supplies callbacks, logo, navigation, guide content, and focus ref. | Playground / FilterLab |
+| `/filter-lab-exercise` | `FilterLabIntroduction`, `FilterLabExercise` | Teaches fixed versus clicked filter values; host passes filter state, stage, filter URL, focus, and continuation callbacks. | FilterLab |
+| `/filter-inspector` | `FilterInspector` | Compares filter clicks with locally recorded event values; needs state, a filter URL, and practice callback. | FilterLab exercise |
+| `/ai-lab-ui` | `AiLabProvider`, `useAiLab`, `useResetAiLab`, `AiIntroduction`, `AiLab` | AI observability lesson with preset request, response, and timeout; provider holds local state. Host passes stage and planner focus callback. | AiLab |
+| `/booking-lab-ui` | `BookingLabProvider`, `useBookingLab`, `BookingLab` | Booking attempt versus confirmed completion lesson; provider holds trip and event state. Host passes stage and booking focus callback. | BookingLab |
+| `/stay-lab-ui` | `StayLabProvider`, `useStayLab`, `StayLab` | Connects stay view events to listing IDs; host passes path and renders stay links. | StayLab |
+| `/replay-recorder` | `ReplayProvider`, `useReplay` | Records the current tab locally or runs a ghost visit with rrweb; pass `open` and `pathname`. | ReplayLab / Playground |
+| `/replay-lab-ui` | `ReplayLab`, `ReplayRecordingBar`, `ReplayLabViewState` | Replay lesson and recording status; host passes stage, replay state, return link, and player. | ReplayLab |
+| `/session-player` | `SessionPlayer` | Plays an rrweb recording; pass recorded `events`. | ReplayLab |
+| `/lab-navigation` | `LabNavigationView` | All labs, previous step, and reset controls; host supplies actions. | FilterLab adapter |
+| `/lab-completion-view` | `LabCompletionView` | Recap for one completed lab; host supplies choose/review actions and heading ref. | LabCompletion |
+| `/lab-checklist` | `LabChecklist` | Step list with done/current/upcoming states; pass `label` and `items`. | Lab UI |
+| `/lab-choices` | `LabChoices` | Accessible radio choice group; pass `label`, `value`, `options`, and `onChange`. | Lab UI |
+| `/finish-lab-button` | `FinishLabButton` | Standard finish action; pass `onClick`. | Lab UI |
+
+The state modules below contain reducers, types, fixtures, and formatting helpers. They have no React UI:
+
+| Import path | Purpose | Used in Twig |
+| --- | --- | --- |
+| `/filter-lab` | Filter event state, validation, feedback, and example code | FilterLab and filter inspector |
+| `/ai-lab` | AI request/response fixtures, event state, checks, and example code | AiLab |
+| `/booking-lab` | Booking attempt/completion state and example code | BookingLab |
+| `/stay-lab` | Stay view event state and example code | StayLab |
+| `/replay-lab` | Replay frame types and display helpers | ReplayLab |
+
+## Styles and assets
+
+| Import path | Use |
+| --- | --- |
+| `/catalog.css` | Twig website views and the read-only preview; includes Twig’s Halfre font. |
+| `/lab.css` | Playground and lab UI; scope it under `.vac-app .vac-developer-theme`. Its PostHog-styled UI uses RoundHog. |
+| `/assets/*` | Package font and image files referenced by the styles or explicitly imported by a host. |
+
+Do not apply Twig typography to the PostHog event inspector in the pocket guide. That inspector, the guide prose, and “Explore Twig” links belong to PostHog.com.

package/docs/integration.md

@@ -0,0 +1,59 @@
+# Integration and updates
+
+## What lives where
+
+| Place | Owns |
+| --- | --- |
+| **This repo** | Reusable Twig views and catalog, the five labs’ UI and local state, playground panels, replay recorder/player, CSS, assets, tests, and gallery. |
+| **Twig.com** | Full website pages, Next.js routes, stay images and links, playground placement, navigation, and focus/scroll behavior. It currently imports a **local workspace copy** of the package. |
+| **PostHog.com** | PostHog 101 prose, code and event examples, PostHog event inspector, Twig introduction screenshot, and guide navigation. Importing the read-only Twig preview from this package is **planned**, not done. |
+
+## Authoring scenarios
+
+**Update a site only when that site needs the change.** Package releases do not change either site automatically. The sites may use different package versions while their needs differ.
+
+| You want to… | Change here? | Change Twig.com? | Change PostHog.com? |
+| --- | --- | --- | --- |
+| Add a lab to Twig's playground only | Yes, for reusable lesson UI and local simulation logic | Add the lab to the page and update the package version | No |
+| Add a Twig lab and teach it in PostHog 101 | Yes, for the lab and any focused, read-only view the guide needs | Add the lab and update the package version | Write the guide and update its package version **if** it uses new exports or behavior |
+| Write PostHog 101 content with an existing package view | No | No | Edit the guide; keep its current version if that view is already available there |
+
+Real event calls tied to a Twig page belong in Twig.com. They need a package change only when shared lab UI or behavior changes. If a guide needs a view that exists **only** inside Twig.com, extract that view into this package first. The guide should use focused views, not embed the full interactive lab.
+
+During the current migration, Twig.com still uses a local workspace copy, and PostHog.com has not installed this package. The version-update steps above apply once the package is published and installed.
+
+## How a host uses the package
+
+1. Pick an export in the [component reference](components.md). A website control such as `StayFilters` needs state and callbacks from the host; a read-only view such as `BrowseStaysPreview` needs only its display props.
+2. Load `catalog.css` for Twig views. Load `lab.css` for a full playground and wrap its UI in `.vac-app .vac-developer-theme`. Keep the guide’s PostHog UI outside that scope.
+3. For the playground, put `ReplayProvider` and `StayLabProvider` above `PlaygroundLabProvider`. Pass the current path, navigation callbacks, and focus actions from the host. Twig.com’s adapters in `src/components/vacation/` show the current setup.
+4. For a PostHog guide embed, use only the focused Twig view inside a Shadow DOM wrapper so host CSS does not change it. Keep click animation, if present, with that Twig view; place the PostHog event inspector and guide CTA outside the shadow root. The wrapper and package integration are not built yet.
+
+The playground provider order is:
+
+```tsx
+<ReplayProvider open={open} pathname={pathname}>
+  <StayLabProvider>
+    <PlaygroundLabProvider active={open && isDiscoverPage} bookingEnabled={open && isStayPage}>
+      <TwigPageAndPlayground />
+    </PlaygroundLabProvider>
+  </StayLabProvider>
+</ReplayProvider>
+```
+
+## How changes reach the sites
+
+1. Change this repo. Use the [workbench](workbench.md) to click through the affected view or lab as you build it. Run `npm test`, `npm run workbench:build`, and `npm run gallery`; review the relevant preview. Run `npm pack --dry-run` before a release.
+2. Until npm publishing is set up, mirror reviewed package changes into Twig.com’s `packages/twig-components/` workspace copy. Compare copies before calling them in sync. PostHog.com has no package integration to update yet.
+3. After publishing is configured, release a version and update the pinned version in each site that needs the change. A published package does **not** update sites on its own.
+4. Build each changed site and inspect the affected page at narrow and wide widths, in light and dark themes, and with reduced motion. Check that Twig styling stays inside Twig UI and the PostHog inspector keeps PostHog styling.
+
+Dependabot proposes dependency updates each week after a seven-day cooldown for routine releases. Security updates are not delayed by that cooldown. Do not describe local workspace changes as a published package release.
+
+## First npm release and later updates
+
+The package is not published yet. The first `0.1.0` release must be published by an authorized `@posthog` npm maintainer with npm two-factor authentication after this PR is reviewed and merged. From a clean `main` checkout, run `npm ci`, `npm test`, and `npm pack --dry-run`; verify the package name, version, and contents. Then run `npm login` and `npm publish --access public`. Do not store an npm token in GitHub.
+
+After the first release, configure npm trusted publishing for **PostHog/twig-components**, workflow **`publish.yml`**, environment **`npm-publish`**, and allow direct publishing. Protect that GitHub environment so only `main` may deploy and a reviewer must approve each run. Then release a new version by merging its reviewed version change to `main` and manually running **Publish to npm** on `main`. The workflow tests and previews the package before publishing with a short-lived identity token. Never run it from a feature branch.
+
+After the first workflow release succeeds, set the package's npm **Publishing access** to **Require two-factor authentication and disallow tokens**. Verify the version and provenance on npm, then update only the consuming sites that need it. See [npm's trusted publishing guide](https://docs.npmjs.com/trusted-publishers/) for the npm settings.

package/docs/workbench.md

@@ -0,0 +1,37 @@
+# Develop with the workbench
+
+The workbench is a local browser preview for package components. It uses local examples, so you can build and click through a component without starting Twig.com or signing in to PostHog.
+
+## Start it
+
+From this repo:
+
+```sh
+npm ci
+npm run workbench
+```
+
+Open the URL printed in the terminal (normally `http://127.0.0.1:5173`). Choose **Twig views** or a lab from the left menu. Changes in `src/`, `workbench/App.tsx`, and the CSS refresh the page while the server runs. Stop it with `Ctrl+C`.
+
+## Add or change a component
+
+1. Build the reusable UI in `src/`. Keep site routes, navigation, and real PostHog event calls in Twig.com.
+2. If it is a new public component, add its import path to `package.json` → `exports` and describe it in [components.md](components.md). Use a `.js` extension for imports between TypeScript source files, as the existing components do.
+3. Add a preview to `workbench/App.tsx`. Import directly from `../src/` so edits appear immediately. Add it to an existing view, or add a menu entry for a distinct component.
+4. Pass example props and local callbacks. For a clickable component, let the preview own its state with React's `useState` or the package reducer. The **Filter lab** preview shows the pattern: click a Twig filter, update local state, then inspect the event.
+5. Check the states someone will actually see: initial, clicked or changed, success or error, narrow width, and keyboard focus. For a lab, click through the whole lesson, not just its first screen.
+
+The workbench's AI and booking actions use fixtures. The replay tab previews lesson states with a fixture; test actual recording and any site routing in Twig.com. Never put credentials or real visitor data in a fixture.
+
+## Before review
+
+```sh
+npm test
+npm run workbench:build
+npm run gallery
+npm pack --dry-run
+```
+
+`npm test` checks the package behavior. `workbench:build` checks that previews type-check and bundle. `gallery` produces static snapshots for visual review. `npm pack --dry-run` shows what would ship; the workbench itself is development-only and is excluded from the npm package.
+
+When the component is used on Twig.com, check it there too. If PostHog 101 uses it, also check the guide's Shadow DOM styling and keep its PostHog inspector outside that boundary. See [integration and updates](integration.md) for how changes reach each site.