# Preview Scenarios

A **scenario** is a real-world surface your template appears in. In [Local Template Preview](/developer/guides/local-preview.md), the toolbar lets you switch between scenarios, each pairing a host page with a placement config (the parameters passed to the production SDK's `renderActions()`).

`allegro-preview` ships three built-in scenarios:

| Tab                  | Description                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------- |
| **Standalone**       | Template rendered on its own in an isolated iframe                                          |
| **Article · Append** | Template injected after the full content of a mock article                                  |
| **Article · Cut**    | Template injected after paragraph 3 of a mock article using the `truncate` placement method |

## Custom Scenarios[​](#custom-scenarios "Direct link to Custom Scenarios")

Define your own scenarios to preview templates inside the real surfaces of your site — a paywalled article, a homepage rail, a newsletter shell. Create an `.allegro-preview/` folder at the root of your templates directory, with one subfolder per scenario:

```text
.allegro-preview/
├── paywalled-article/
│   ├── scenario.json     # required: name + placement config
│   ├── host.html         # optional: your mock host page markup
│   └── host.css          # optional: host page styles
└── homepage-rail/
    ├── scenario.json
    └── host.html

```

Each `scenario.json` mirrors the production SDK's placement parameters:

```json
{
  "name": "Paywalled Article",
  "target_selector": "#article-body",
  "placement_method": "truncate",
  "truncation_unit": "paragraphs",
  "truncation_count": 4,
  "truncation_style": "cut"
}

```

| Key                | Required                    | Notes                                          |
| ------------------ | --------------------------- | ---------------------------------------------- |
| `name`             | Yes                         | Label shown on the scenario tab.               |
| `target_selector`  | When `host.html` is present | CSS selector in your host page to inject into. |
| `placement_method` | When injecting              | `truncate` or `append`.                        |
| `truncation_unit`  | When `truncate`             | e.g. `paragraphs`.                             |
| `truncation_count` | When `truncate`             | Whole number.                                  |
| `truncation_style` | When `truncate`             | e.g. `cut`.                                    |

How the host page is chosen:

* **With `host.html`** — your markup is the page, and the template is injected into `target_selector` using `placement_method`. `host.css` is included automatically.
* **Without `host.html`** — the template renders standalone, and `target_selector` is ignored.

Custom scenarios appear as additional tabs alongside the built-in ones and live-reload when you edit them.

## Example: a custom host page[​](#example-a-custom-host-page "Direct link to Example: a custom host page")

A scenario is a folder of up to three files. The `host.html` file is the full page your template is injected into — it is plain HTML, styled with `host.css`, with behavior added through an inline `<script>` (there is no separate `host.js` file; host-page JavaScript lives inside `host.html`).

`.allegro-preview/paywalled-article/scenario.json`:

```json
{
  "name": "Paywalled Article",
  "target_selector": "#article-body",
  "placement_method": "truncate",
  "truncation_unit": "paragraphs",
  "truncation_count": 4,
  "truncation_style": "cut"
}

```

`.allegro-preview/paywalled-article/host.html`:

```html
<article class="post">
  <h1>The Future of Local News</h1>
  <p class="byline">By Jordan Ellison · March 14, 2026</p>

  <div id="article-body">
    <p>The city council voted unanimously Tuesday to approve a sweeping new transit plan.</p>
    <p>Mayor Ellison called the decision a turning point for how the region gets around.</p>
    <p>The plan upgrades 14 bus lines and adds three new light-rail corridors downtown.</p>
    <p>Critics warn the projected cost may climb once land acquisition is factored in.</p>
  </div>

  <script>
    // Host-page JS runs in the preview exactly as it would on your real site —
    // useful for mimicking a paywall, lazy-loaded content, or analytics hooks.
    const body = document.getElementById('article-body');
    body.querySelectorAll('p').forEach((p, index) => {
      p.dataset.paragraph = String(index + 1);
    });
    console.log(`[host] article rendered with ${body.children.length} paragraphs`);
  </script>
</article>

```

`.allegro-preview/paywalled-article/host.css`:

```css
.post {
  max-width: 680px;
  margin: 0 auto;
  padding: 32px 24px;
  font-family: Georgia, serif;
  line-height: 1.7;
}

.post .byline {
  color: #6b7280;
  font-family: system-ui, sans-serif;
  font-size: 0.85rem;
}

```

With this `scenario.json`, the template is injected into `#article-body` using the `truncate` method after the fourth paragraph — reproducing how it appears mid-article on your site, including any host-page scripts and styles.

note

The `.allegro-preview/` folder is ignored by the GitHub template sync — it never becomes a template and never produces a sync warning. Keep your scenarios in your repo without affecting what syncs to Allegro.