### Install Fragtml Package

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Installs the Fragtml library using npm. This is a prerequisite for using Fragtml in your project.

```sh
npm install fragtml
```

--------------------------------

### Start a Named Fragment Range

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Illustrates the usage of `html.fragment.start(id)` to mark the beginning of a named fragment within a template.

```javascript
${html.fragment.start('archive-ui')}
```

--------------------------------

### Using Fragment Boundaries in a Template

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Demonstrates how to use start and end fragment boundary objects within an HTML template literal to define a fragment.

```javascript
html`
  ${html.fragment.start('archive-ui')}
  <button>Archive</button>
  ${html.fragment.end}
`
```

--------------------------------

### Boolean Attributes - Falsey Example

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Example showing the output when the condition for a boolean attribute is falsey.

```html
<button>Save</button>
```

--------------------------------

### Render Archive Button Fragment with FragTML

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

This example demonstrates rendering only a specific fragment, the archive button, by providing a `fragmentId` to the `contactDetail` function. This allows for partial updates or targeted rendering.

```javascript
contactDetail({ contact, fragmentId: 'archive-ui' })
```

--------------------------------

### Editor Highlighting with '/* html */' Marker

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

This example shows how to ensure editor HTML highlighting works correctly when using fragment aliases by adding an `/* html */` marker. It uses the `frag` alias and defines a template with an archive button.

```javascript
const h = frag(fragmentId)

return h/* html */`
  <article>
    <h3>${contact.name}</h3>

    <div hx-target="this">
      ${h.fragment.start('archive-ui')}
      <button>Archive</button>
      ${h.fragment.end}
    </div>
  </article>
`
```

--------------------------------

### Named and Unnamed Fragment Boundary Objects

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Illustrates the structure of start and end boundary objects used for fragment support. The start boundary includes an ID, while the end boundary is unnamed.

```javascript
{
  [fragmentBoundarySymbol]: true,
  kind: 'start',
  id: 'archive-ui'
}
```

```javascript
{
  [fragmentBoundarySymbol]: true,
  kind: 'end'
}
```

--------------------------------

### Boolean Attributes - Truthy Example

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Example showing the output when the condition for a boolean attribute is truthy.

```html
<button disabled>Save</button>
```

--------------------------------

### Nested Template Composition Example

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Shows how a nested template result is treated as a recognizable library-created value, allowing parent templates to insert it without escaping its markup.

```javascript
const child = html`<span>${'<Bret>'}</span>`
const parent = html`<div>${child}</div>`

render(parent)
// '<div><span>&lt;Bret&gt;</span></div>'
```

--------------------------------

### End a Fragment Range

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Demonstrates the usage of `html.fragment.end` to close the most recently opened fragment range started with `html.fragment.start()`.

```javascript
${html.fragment.end}
```

--------------------------------

### Example of Stale Cache Behavior

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Demonstrates how caching final rendered strings can lead to stale output when substitutions are mutated. `HtmlResult` should render from its captured template and substitutions each time it is called.

```javascript
const items = ['a']
const result = html`${items}`

items.push('b')

render(result)
// should reflect the current substitution semantics, not a stale first-render cache
```

--------------------------------

### Fragment Markers with FragmentTemplateTypes

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

This example demonstrates using `FragmentTemplateTypes` to define context types for different fragments within a single template. It shows how to define fragment IDs, their required context types, and the overall context for the full template. The `PageArgs` type enforces context requirements at the call boundary.

```typescript
import { frag, render } from 'fragtml'
import type {
  FragmentTemplateTypes
} from 'fragtml/types.js'

type InnerPageContext = {
  text: string
}

type OuterPageContext = InnerPageContext & {
  title: string
}

type FullPageContext = OuterPageContext & {
  foo: string
}

type PageTemplate = FragmentTemplateTypes<{
  // Fragment IDs and their required context types.
  fragments: {
    inner: InnerPageContext
    outer: OuterPageContext
  }
  // Context required to render the full template.
  full: FullPageContext
}>

type PageFragment = PageTemplate['fragmentId']
// Resolves to:
// 'inner' | 'outer'

type PageArgs = PageTemplate['args']
// Resolves to:
// | { fragmentId: 'inner', context: InnerPageContext & Record<string, unknown> }
// | { fragmentId: 'outer', context: OuterPageContext & Record<string, unknown> }
// | { fragmentId?: undefined, context: FullPageContext & Record<string, unknown> }

type PageTemplateArgs = PageTemplate['templateArgs']
// Resolves to:
// {
//   fragmentId?: 'inner' | 'outer' | undefined
//   context: {
//     foo?: string
//     title?: string
//     text?: string
//   }
// }

function pageTemplate ({
  context,
  fragmentId
}: PageTemplateArgs) {
  const html = frag<PageFragment>(fragmentId)

  return html`
    <div>${context.foo}</div>

    ${html.fragment.start('outer')}
    <section>
      <h2>${context.title}</h2>

      ${html.fragment.start('inner')}
      <button>Inner update target</button>
      <div>${context.text}</div>
      ${html.fragment.end}
    </section>
    ${html.fragment.end}
  `
}

export function page (args: PageArgs) {
  return render(pageTemplate(args))
}

// These calls are still type-safe: PageArgs enforces the required context
// fields for each fragment target at the public call boundary.
page({
  fragmentId: 'inner',
  context: { text: 'Updated body text' }
})

page({
  fragmentId: 'outer',
  context: {
    // Extra already-loaded data is allowed.
    foo: 'Full page field',
    title: 'Outer fragment title',
    text: 'Updated body text'
  }
})

page({
  context: {
    foo: 'Full page field',
    title: 'Outer fragment title',
    text: 'Updated body text'
  }
})

// @ts-expect-error outer fragments require both title and text.
page({
  fragmentId: 'outer',
  context: { text: 'Missing the outer title' }
})
```

--------------------------------

### Dashboard Template with Fragments

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Defines a dashboard template using Fragtml fragments, allowing for partial updates to specific sections like account information or feed items while keeping the overall page structure intact. Includes type definitions for context and examples of rendering different fragments.

```typescript
import html, { render } from 'fragtml'
import type { FragmentTemplateTypes } from 'fragtml/types.js'

function dashboardTemplate ({ 
  account,
  feed,
  fragmentId
}: DashboardTemplate['templateArgs']) {
  return html<DashboardTemplate['fragmentId']>(fragmentId)/* html */`
    <main>
      <h1>Workspace</h1>

      ${html.fragment.start('account-root')}
      <section id="account">
        <h2>${account.title}</h2>
        <p>${account.name}</p>

        ${html.fragment.start('account-primary-action')}
        <button hx-patch="/accounts/${account.id}">
          ${account.archived ? 'Restore' : 'Archive'}
        </button>
        ${html.fragment.end}
      </section>
      ${html.fragment.end}

      ${html.fragment.start('feed-root')}
      <section id="feed">
        <h2>${feed.title}</h2>
        <article>
          ${feed.latest.title}

          ${html.fragment.start('feed-item-menu')}
          <menu>
            <button hx-get="/feed/${feed.latest.id}/menu">Open</button>
          </menu>
          ${html.fragment.end}
        </article>
      </section>
      ${html.fragment.end}
    </main>
  `
}

export function dashboard (args: DashboardTemplate['args']) {
  return render(dashboardTemplate(args))
}

// Rendering different fragments, with type safety
dashboard({
  account: {
    id: 'acct_123',
    title: 'Account',
    name: 'Acme',
    archived: false
  },
  feed: {
    title: 'Feed',
    latest: {
      id: 'item_123',
      title: 'New signup'
    }
  }
})

dashboard({
  fragmentId: 'account-primary-action',
  account: {
    id: 'acct_123',
    archived: false
  }
})

dashboard({
  fragmentId: 'feed-item-menu',
  feed: {
    latest: {
      id: 'item_123'
    }
  }
})

type AccountActionContext = {
  account: { 
    id: string
    archived: boolean
  }
}

type AccountRootContext = AccountActionContext & {
  account: AccountActionContext['account'] & {
    title: string
    name: string
  }
}

type FeedItemMenuContext = {
  feed: {
    latest: {
      id: string
    }
  }
}

type FeedRootContext = FeedItemMenuContext & {
  feed: FeedItemMenuContext['feed'] & {
    title: string
    latest: FeedItemMenuContext['feed']['latest'] & {
      title: string
    }
  }
}

type DashboardTemplate = FragmentTemplateTypes<{
  fragments: {
    'account-root': AccountRootContext
    'account-primary-action': AccountActionContext
    'feed-root': FeedRootContext
    'feed-item-menu': FeedItemMenuContext
  }
  full: AccountRootContext & FeedRootContext
}>
```

--------------------------------

### Importing fragtml

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Demonstrates how to import the default `html` tag and other utilities like `render` from the 'fragtml' library. Aliasing is shown for cases where both default and named imports are needed.

```javascript
import html, { createHtml, raw, render } from 'fragtml'
```

```javascript
import defaultHtml, { html, render } from 'fragtml'
```

--------------------------------

### Running Tests and Build

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Commands to run tests and build the project. Ensure all tests pass and the build completes successfully.

```sh
npm test
npm run build
```

--------------------------------

### Fragment Factory Usage

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Demonstrates how to use the `createHtml` factory to create a local `html` tag instance and its associated fragment helpers for managing dynamic HTML fragments.

```typescript
const localHtml = createHtml('foo')
localHtml`...`
localHtml.fragment.start('foo')
localHtml.raw('<em>trusted</em>')
```

--------------------------------

### Defining and Rendering Fragments with Fragml

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Illustrates how to define explicit fragment boundaries using `h.fragment.start` and `h.fragment.end` for targeted rendering. This approach keeps fragment content visually inline.

```javascript
import html, { render } from 'fragtml'

export function contactDetail ({ contact, fragmentId }) {
  const h = html({ fragmentId })

  return render(h`
    <html>
      <body>
        <div hx-target="this">
          ${h.fragment.start('archive-ui')}
          ${contact.archived
            ? h`<button hx-patch="/contacts/${contact.id}/unarchive">Unarchive</button>`
            : h`<button hx-delete="/contacts/${contact.id}">Archive</button>`}
          ${h.fragment.end}
        </div>

        <h3>Contact</h3>
        <p>${contact.email}</p>
      </body>
    </html>
  `)
}
```

--------------------------------

### Defining Fragments with Boundary Tokens

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Illustrates how to define named fragments within a template using `html.fragment.start` and `html.fragment.end` boundary tokens.

```javascript
${html.fragment.start('archive-ui')}
...
${html.fragment.end}
```

--------------------------------

### Basic fragtml Template Tag Usage

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Demonstrates the basic usage of the `html` template tag for creating HTML structures with dynamic values.

```javascript
html`<p>${value}</p>`
```

--------------------------------

### Callable HTML Tag with Properties

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Demonstrates how to use the html tag function at runtime, exposing helper properties for fragments and raw HTML.

```javascript
html.fragment = createFragmentHelpers()
html.raw = raw

const h = html({ fragmentId })
h.fragment = html.fragment
h.raw = raw
```

--------------------------------

### Basic HTML Rendering

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Demonstrates basic HTML string creation and rendering using the html tag and render function. Interpolated values are escaped by default.

```javascript
import html, { render } from 'fragtml'

const name = '<Bret>'
const result = html`<p>Hello ${name}</p>`

render(result)
// '<p>Hello &lt;Bret&gt;</p>'
```

--------------------------------

### Publish a Release to npm

Source: https://github.com/bcomnes/fragtml/blob/master/CONTRIBUTING.md

After updating the version, use this command to push your local branch and tags, create a GitHub release, and publish the package to npm. This command also performs a gh-release.

```bash
npm publish
```

--------------------------------

### Create a Release with npm Version

Source: https://github.com/bcomnes/fragtml/blob/master/CONTRIBUTING.md

Use this command to update the version number and automatically generate a changelog for a new release. Ensure your git workspace is clean before running.

```bash
npm version {patch, minor, major}
```

--------------------------------

### html.fragment.start(id)

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Marks the beginning of a named fragment range within a template, allowing for targeted rendering of specific sections.

```APIDOC
## `html.fragment.start(id)`

Starts a named fragment range.

```js
${html.fragment.start('archive-ui')}
```
```

--------------------------------

### Import fragtml Type Guards

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Demonstrates importing and using public type guard functions provided by fragtml to check the type of values.

```javascript
import {
  isFragmentBoundary,
  isHtmlResult,
  isRawHtml
} from 'fragtml'
```

--------------------------------

### Import fragtml TypeScript Types

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Demonstrates importing type-only aliases from `fragtml/types.js` for use in TypeScript projects.

```typescript
import type {
  FragmentArgs,
  FragmentIdOf,
  FragmentTemplateArgs,
  FragmentTemplateTypes,
  HtmlRenderable,
  HtmlResult,
  HtmlTag,
  RawHtml,
  RenderOptions
} from 'fragtml/types.js'
```

--------------------------------

### Template Caching Implementation

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Shows a recommended implementation for caching static template processing using a `WeakMap`. This approach caches precomputed metadata for a given template literal call site.

```javascript
const templateCache = new WeakMap()

function compileTemplate (strings, mode) {
  let compiled = templateCache.get(strings)

  if (!compiled) {
    compiled = {
      strings,
      mode,
      // static preprocessing metadata here
    }
    templateCache.set(strings, compiled)
  }

  return compiled
}
```

--------------------------------

### Render Full Page with FragTML

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

This snippet shows how to render an entire HTML page using the `contactDetailTemplate` function and the `render` utility from FragTML. It includes dynamic content based on contact details and HTMX attributes for interactivity.

```javascript
import html, { render } from 'fragtml'

function contactDetailTemplate ({ contact, fragmentId }) {
  return html(fragmentId)`
    <html>
      <body>
        <div hx-target="this">
          ${html.fragment.start('archive-ui')}
          ${contact.archived
            ? html`<button hx-patch="/contacts/${contact.id}/unarchive">Unarchive</button>`
            : html`<button hx-delete="/contacts/${contact.id}">Archive</button>`}
          ${html.fragment.end}
        </div>

        <h3>Contact</h3>
        <p>${contact.email}</p>
      </body>
    </html>
  `
}

export function contactDetail (args) {
  return render(contactDetailTemplate(args))
}
```

--------------------------------

### Safe Nested Composition with Fragml

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Demonstrates how to use `html` to create nested template objects that can be safely rendered. Interpolated strings are escaped by default.

```javascript
import html, { render } from 'fragtml'

const button = html`<button>${'<Archive>'}</button>`

const panel = html`
  <div hx-target="this">
    ${button}
  </div>
`

render(panel)
// '<div hx-target="this"><button>&lt;Archive&gt;</button></div>'
```

--------------------------------

### Render Root Fragment with fragtml

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Renders the entire 'profile' fragment, including its nested content. This is useful for updating a large section of the page.

```javascript
page({ fragmentId: 'profile' })
// '<section>
//   <h2>Profile</h2>
//
//   <button>Edit profile</button>
// </section>'
```

--------------------------------

### Using html.raw Helper

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Shows that `html.raw` is an alias for the `raw` helper, allowing trusted HTML insertion directly from the `html` tag object.

```javascript
html.raw === raw
// true
```

--------------------------------

### Import fragtml Error Classes

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Shows how to import specific error classes from fragtml for error handling and type checking.

```javascript
import {
  DuplicateFragmentError,
  FragmentBoundaryError,
  FragmentNotFoundError
} from 'fragtml'
```

--------------------------------

### Raw HTML Helper Usage

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Shows how to use the `raw` helper function or the `.raw()` method on an `html` tag instance to insert trusted, unescaped HTML content.

```typescript
html.raw('<em>trusted</em>')
raw('<em>trusted</em>')
```

--------------------------------

### Rendering XML/RSS Feed

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Demonstrates rendering XML-shaped documents, such as RSS feeds, with FragTML. Static markup is preserved, and interpolated values are escaped.

```javascript
import html, { render } from 'fragtml'

const siteUrl = 'https://example.com'
const posts = [
  {
    title: 'Hello & welcome',
    href: '/posts/hello'
  }
]

const feed = html`<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>Example Feed</title>
    <link>${siteUrl}</link>
    ${posts.map(post => html`
      <item>
        <title>${post.title}</title>
        <link>${siteUrl}${post.href}</link>
        <guid>${siteUrl}${post.href}</guid>
      </item>
    `)}
  </channel>
</rss>
`

render(feed)
// '<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">...'
```

--------------------------------

### Returning Rendered HTML from Route Handlers

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Shows how to return rendered HTML from a route handler. The render function should be used at route-handler boundaries.

```javascript
return render(html`<h1>${title}</h1>`)
```

--------------------------------

### Using fragtml Alias for Editor Highlighting

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Illustrates using `frag` as an alias for `html` and assigning it to a local variable `h` for better editor highlighting, especially with the `/* html */` marker.

```javascript
import { frag } from 'fragtml'

const html = frag(fragmentId)

const h = frag(fragmentId)

return h/* html */`<p>${value}</p>`
```

--------------------------------

### Trusted Raw HTML Insertion

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Demonstrates how to insert pre-trusted HTML content into a template using the `raw` helper. The content provided to `raw` is not escaped.

```javascript
import html, { raw, render } from 'fragtml'

const result = html`<p>${raw('<strong>trusted</strong>')}</p>`

render(result)
// '<p><strong>trusted</strong></p>'
```

--------------------------------

### Creating Raw Trusted HTML

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Demonstrates the use of the `.raw` helper to create a separate branded raw/trusted value for HTML content that should not be escaped.

```javascript
html.raw('<em>trusted</em>')
```

--------------------------------

### Basic HTML Tag Usage

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Illustrates the basic usage of the `html` tag for creating safe HTML interpolations and rendering the result.

```typescript
import html, { createHtml, html as namedHtml, raw, render } from 'fragtml'

const result = html`<p>${'safe'}</p>`
render(result)
String(result)
```

--------------------------------

### Mark Trusted HTML with raw

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Shows how to use the `raw` function to mark HTML content as trusted, preventing it from being escaped during rendering.

```javascript
html`<p>${raw('<strong>trusted</strong>')}</p>`
```

--------------------------------

### Select Fragment with ID using html Tag

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Shows how to select and render a specific fragment from a template by passing its ID to the `html` tag.

```javascript
html('name')`...`
```

```javascript
html({ fragmentId: 'name' })`...`
```

--------------------------------

### Using a Bound Tag for Fragment Definition

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Demonstrates a common pattern where a bound tag `h` is created with a `fragmentId` for cleaner template syntax, especially when editors might not highlight call expressions as reliably.

```javascript
({ fragmentId, ...data }) => {
  const h = html({ fragmentId })
  return render(h`<div>...</div>`)
}
```

--------------------------------

### Shorter Render-Target Overload for Fragments

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Demonstrates the convenience overload `html('fragment-id')` which is equivalent to `html({ fragmentId: 'fragment-id' })` for defining fragments.

```javascript
html('archive-ui')`...`
```

--------------------------------

### Direct String Conversion of Template Results

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Demonstrates the various ways a template result object can be converted to a string, including String(), toString(), and template literal interpolation.

```javascript
const result = html`<p>${name}</p>`

String(result)
result.toString()
`${result}`
```

--------------------------------

### render(value)

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

The `render` function converts a `fragtml` tagged template result into a primitive string representation of the HTML.

```APIDOC
## `render(value)`

Converts a `fragtml` result to a primitive string.

```js
render(html`<p>${value}</p>`)
```
```

--------------------------------

### Render fragtml Result to String

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Demonstrates how to convert a `fragtml` `HtmlResult` object into a primitive string using the `render` function.

```javascript
render(html`<p>${value}</p>`)
```

--------------------------------

### Rendering Raw HTML Content within Fragments

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Explains how to render trusted HTML content directly within a fragment using the `h.raw()` helper, while other interpolations follow safe rules.

```javascript
const h = html({ fragmentId })

render(h`
  ${h.fragment.start('raw-widget')}
  <div>${h.raw(trustedHtml)}</div>
  ${h.fragment.end}
`)
```

--------------------------------

### Basic Safe HTML Rendering

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Illustrates the default safe behavior of the `html` tag, where interpolated values are automatically HTML-escaped. Shows conversion to a primitive string using `String()` and the `render()` function.

```javascript
import html, { render } from 'fragtml'

const name = '<Bret>'

const result = html`<p>Hello ${name}</p>`

String(result)
// '<p>Hello &lt;Bret&gt;</p>'

render(result)
// '<p>Hello &lt;Bret&gt;</p>'
```

--------------------------------

### Rendering Trusted Raw HTML

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Demonstrates using the `raw()` function or `html.raw` to render HTML content that should not be escaped. Only pass trusted HTML to `raw()`.

```javascript
import html, { raw, render } from 'fragtml'

render(html`<p>${raw('<strong>trusted</strong>')}</p>`)
// '<p><strong>trusted</strong></p>'

html.raw === raw

render(html`<p>${html.raw('<em>trusted</em>')}</p>`)
// '<p><em>trusted</em></p>'
```

--------------------------------

### Avoid Wrapping Entire Template in Outer Fragment

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Demonstrates an antipattern of wrapping the entire template in an outer fragment, which adds a fake target without changing output.

```javascript
function pageTemplate ({ fragmentId }) {
  return html(fragmentId)`
    ${html.fragment.start('page')}
    <main>
      <h1>${title}</h1>
      <p>${body}</p>
    </main>
    ${html.fragment.end}
  `
}
```

--------------------------------

### Composed Dashboard Template with Function Composition

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Builds a dashboard using function composition for reusable partial templates. This approach simplifies types and reduces moving parts compared to fragments, but spreads the full-page structure across multiple functions.

```typescript
function accountPrimaryAction (context: AccountActionContext) {
  return html`
    <button hx-patch="/accounts/${context.account.id}">
      ${context.account.archived ? 'Restore' : 'Archive'}
    </button>
  `
}

function accountRoot (context: AccountRootContext) {
  return html`
    <section id="account">
      <h2>${context.account.title}</h2>
      <p>${context.account.name}</p>
      ${accountPrimaryAction(context)}
    </section>
  `
}

function feedItemMenu (context: FeedItemMenuContext) {
  return html`
    <menu>
      <button hx-get="/feed/${context.feed.latest.id}/menu">Open</button>
    </menu>
  `
}

function feedRoot (context: FeedRootContext) {
  return html`
    <section id="feed">
      <h2>${context.feed.title}</h2>
      <article>
        ${context.feed.latest.title}
        ${feedItemMenu(context)}
      </article>
    </section>
  `
}

function composedDashboardTemplate (context: AccountRootContext & FeedRootContext) {
  return html`
    <main>
      <h1>Workspace</h1>
      ${accountRoot(context)}
      ${feedRoot(context)}
    </main>
  `
}

export function composedDashboard (context: AccountRootContext & FeedRootContext) {
  return render(composedDashboardTemplate(context))
}
```

--------------------------------

### Render Nested Fragment with fragtml

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Renders only the 'profile-actions' nested fragment. This is useful for updating small, specific parts of the UI independently.

```javascript
page({ fragmentId: 'profile-actions' })
// '<button>Edit profile</button>'
```

--------------------------------

### Prefer Direct Template Rendering Without Outer Fragment

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Shows the preferred way to render a template directly, avoiding unnecessary outer fragments for full template rendering.

```javascript
function pageTemplate ({ fragmentId }) {
  return html(fragmentId)`
    <main>
      <h1>${title}</h1>
      <p>${body}</p>
    </main>
  `
}
```

--------------------------------

### Build Public Argument Union with FragmentArgs

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Constructs the public argument union type using FragmentArgs, combining fragment contexts and the full-page context.

```typescript
type PageArgs = FragmentArgs<{
  inner: InnerPageContext
  outer: OuterPageContext
}, FullPageContext>

// Equivalent to:
// | { fragmentId: 'inner', context: InnerPageContext & Record<string, unknown> }
// | { fragmentId: 'outer', context: OuterPageContext & Record<string, unknown> }
// | { fragmentId?: undefined, context: FullPageContext & Record<string, unknown> }
```

--------------------------------

### Avoiding Shadowing with createHtml Alias

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Shows how to use `createHtml` when the local tag needs to be named `html` to prevent JavaScript name shadowing, ensuring the template tag is a simple identifier.

```javascript
import { createHtml, render } from 'fragtml'

export function view ({ fragmentId }) {
  const html = createHtml({ fragmentId })

  return render(html`
    ${html.fragment.start('main')}
    <main>...</main>
    ${html.fragment.end}
  `)
}
```

--------------------------------

### Define Nested Fragments with fragtml

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Defines a page template with nested fragments for profile and activity sections. This allows for independent rendering of parent and child regions.

```javascript
import html, { render } from 'fragtml'

function pageTemplate ({ fragmentId }) {
  return html(fragmentId)`
    ${html.fragment.start('profile')}
    <section>
      <h2>Profile</h2>

      ${html.fragment.start('profile-actions')}
      <button>Edit profile</button>
      ${html.fragment.end}
    </section>
    ${html.fragment.end}

    ${html.fragment.start('activity')}
    <section>
      <h2>Activity</h2>

      ${html.fragment.start('activity-row')}
      <article>Recent activity</article>
      ${html.fragment.end}
    </section>
    ${html.fragment.end}
  `
}

export function page (args) {
  return render(pageTemplate(args))
}
```

--------------------------------

### Define Page Template Types

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Defines the types for a page template, including fragment-specific contexts and overall template arguments.

```typescript
type PageTemplate = FragmentTemplateTypes<{
  fragments: {
    inner: InnerPageContext
    outer: OuterPageContext
  }
  full: FullPageContext
}>

type PageArgs = PageTemplate['args']
type PageTemplateArgs = PageTemplate['templateArgs']
```

--------------------------------

### Composing Nested HTML Templates

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Shows how nested `html` results are rendered, with their own substitutions remaining escaped. Arrays are inlined with indentation-aware formatting.

```javascript
const button = html`<button>${'<Archive>'}</button>`

render(html`
  <div hx-target="this">
    ${button}
  </div>
`)
// '<div hx-target="this">
//   <button>&lt;Archive&gt;</button>
// </div>'

const items = ['one', 'two'].map((item) => html`<li>${item}</li>`)

render(html`
  <ul>
    ${items}
  </ul>
`)
// '<ul>
//   <li>one</li>
//   <li>two</li>
// </ul>'
```

--------------------------------

### Preferred Explicit Rendering Boundary

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Illustrates the preferred method for explicit rendering of template results, particularly for route handlers and tests, using the render() function.

```javascript
return render(html`<p>${name}</p>`) 
```

--------------------------------

### Using 'frag' Alias for HTML Templating

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

This snippet illustrates using the `frag` alias for `html` to improve editor highlighting. It defines a template for contact details, including an archive button, within an `<article>` tag.

```javascript
import { frag, render } from 'fragtml'

function contactDetailTemplate ({ contact, fragmentId }) {
  const html = frag(fragmentId)

  return html`
    <article>
      <h3>${contact.name}</h3>
      <p>${contact.email}</p>

      <div hx-target="this">
        ${html.fragment.start('archive-ui')}
        <button>${contact.archived ? 'Unarchive' : 'Archive'}</button>
        ${html.fragment.end}
      </div>
    </article>
  `
}

export function contactDetail (args) {
  return render(contactDetailTemplate(args))
}
```

--------------------------------

### raw(value) / html.raw(value)

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Marks trusted HTML content to be inserted directly without escaping, ensuring that the provided HTML is rendered as-is.

```APIDOC
## `raw(value)` / `html.raw(value)`

Marks trusted HTML so it is inserted without escaping.

```js
html`<p>${raw('<strong>trusted</strong>')}</p>`
```
```

--------------------------------

### Toggle Boolean Attributes with fragtml

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Shows how to use the `?name=${condition}` syntax to conditionally add or remove boolean attributes like `disabled`.

```javascript
html`<button ?disabled=${loading}>Save</button>`
```

--------------------------------

### Toggling Boolean Attributes

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Explains how to use the `?name=${condition}` syntax to toggle boolean attributes. The attribute is rendered if the condition is truthy, and omitted if falsey.

```javascript
render(html`<button ?disabled=${loading}>Save</button>`)
```

--------------------------------

### RawHtml Class

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Represents HTML content that has been explicitly marked as trusted and will not be escaped during rendering.

```APIDOC
## `RawHtml`

Class returned by `raw(value)` and `html.raw(value)`.

```js
import { RawHtml, raw } from 'fragtml'

const trusted = raw('<strong>trusted</strong>')

trusted instanceof RawHtml
```
```

--------------------------------

### HtmlResult Class

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Represents the result of an `html` or `frag` tagged template, providing an object-oriented way to handle HTML output.

```APIDOC
## `HtmlResult`

Class returned by `html` and `frag` tagged templates.

```js
import html, { HtmlResult } from 'fragtml'

const result = html`<p>Hello</p>`

result instanceof HtmlResult
```
```

--------------------------------

### Recommended HtmlResult Class Shape

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Presents the recommended structure for the HtmlResult class, including private fields for compiled template, substitutions, and options, and methods for string conversion.

```javascript
class HtmlResult {
  #compiled
  #substitutions
  #options

  constructor (compiled, substitutions, options) {
    this.#compiled = compiled
    this.#substitutions = substitutions
    this.#options = options
  }

  toString () {
    return render(this)
  }

  valueOf () {
    return render(this)
  }

  [Symbol.toPrimitive] () {
    return render(this)
  }
}
```

--------------------------------

### Composing Typed Template Functions

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

This approach uses function composition to create reusable, typed template functions for smaller pieces of UI. It offers stricter type checking at each composition boundary and is suitable when fragments need to be reused across multiple parent templates. The `render` function is used to render the output of these composed functions.

```typescript
import html, { render } from 'fragtml'

type InnerContext = {
  text: string
}

type OuterContext = InnerContext & {
  title: string
}

type FullContext = OuterContext & {
  foo: string
}

export function inner (context: InnerContext) {
  return html`
    <button>Inner update target</button>
    <div>${context.text}</div>
  `
}

export function outer (context: OuterContext) {
  return html`
    <section>
      <h2>${context.title}</h2>
      ${inner(context)}
    </section>
  `
}

export function full (context: FullContext) {
  return html`
    <div>${context.foo}</div>
    ${outer(context)}
  `
}

render(inner({ text: 'Updated body text' }))

render(outer({
  title: 'Outer section title',
  text: 'Updated body text'
}))

render(full({
  foo: 'Full page field',
  title: 'Outer section title',
  text: 'Updated body text'
}))

// @ts-expect-error outer requires both title and text.
render(outer({ text: 'Missing the outer title' }))
```

--------------------------------

### Escaping Script Tags

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Shows how FragTML automatically escapes potentially harmful HTML content like script tags when interpolating.

```javascript
render(html`<p>${'<script>alert(1)</script>'}</p>`)
// '<p>&lt;script&gt;alert(1)&lt;/script&gt;</p>'
```

--------------------------------

### html Tagged Template

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

The `html` tagged template literal is the primary way to create HTML structures. It supports safe-by-default rendering and can be used with fragment IDs to select specific parts of a template.

```APIDOC
## `html`

Safe-by-default template tag.

```js
html`<p>${value}</p>`
```

Pass a fragment ID before the tagged template to render a selected fragment from that template:

```js
html('name')`...`
html({ fragmentId: 'name' })`...`
```
```

--------------------------------

### createHtml Alias Equivalence

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Confirms that `createHtml` is a strict alias of `html`, intended for use when the local tag must be named `html`.

```javascript
createHtml === html
```

--------------------------------

### Error Classes

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Provides specific error classes for handling issues related to fragment management, such as `DuplicateFragmentError`, `FragmentBoundaryError`, and `FragmentNotFoundError`.

```APIDOC
## Error classes

```js
import {
  DuplicateFragmentError,
  FragmentBoundaryError,
  FragmentNotFoundError
} from 'fragtml'
```
```

--------------------------------

### Type Checking HtmlResult in TypeScript

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Illustrates how to use the `HtmlResult` class both at runtime and as a type in TypeScript, including a type guard function.

```typescript
import { HtmlResult } from 'fragtml'
import type { HtmlResult as HtmlResultType } from 'fragtml/types.js'

function sendHtml (result: HtmlResultType) {
  return result.toString()
}

function isHtmlResultValue (value: unknown): value is HtmlResultType {
  return value instanceof HtmlResult
}
```

--------------------------------

### JSDoc Typedefs for Fragtml

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Provides a set of JSDoc typedefs to define the types for substitutions, render options, and various callback functions used within the Fragtml library.

```javascript
/**
 * @typedef {string | number | bigint | boolean | null | undefined} PrimitiveSubstitution
 * @typedef {PrimitiveSubstitution | HtmlResult | RawHtml | FragmentBoundary | Substitution[]}
 * @typedef {ReadonlyArray<string> & { raw?: readonly string[] }} TemplateStrings
 *
 * @typedef {object}
 * @property {string | undefined} [fragmentId]
 *
 * @callback HtmlTag
 * @param {TemplateStrings} strings
 * @param {...Substitution} substitutions
 * @returns {HtmlResult}
 *
 * @callback RawHelper
 * @param {unknown} value
 * @returns {RawHtml}
 *
 * @callback FragmentBoundaryFactory
 * @param {string} id
 * @returns {FragmentBoundary}
 *
 * @typedef {object}
 * @property {FragmentBoundaryFactory} start
 * @property {FragmentBoundary} end
 *
 * @callback HtmlTagFactory
 * @param {RenderOptions | string}
 * @returns {HtmlTag}
 */
```

--------------------------------

### Escaping Untrusted User Input in Fragml

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Shows how Fragml automatically escapes ordinary strings to prevent untrusted content from being rendered as HTML.

```javascript
const userInput = '<button>not trusted</button>'

render(html`<div>${userInput}</div>`)
// '<div>&lt;button&gt;not trusted&lt;/button&gt;</div>'
```

--------------------------------

### Fragment Boundary Symbol

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Defines a unique symbol for fragment boundary tokens to manage fragment support within the library.

```javascript
const fragmentBoundarySymbol = Symbol('fragtml.fragmentBoundary')
```

--------------------------------

### frag Alias

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

The `frag` function is an alias for `html`, providing flexibility for editor highlighting and repeated use by allowing assignment to a local tag name.

```APIDOC
## `frag`

Alias of `html`, useful when you want a local tag name for editor highlighting or repeated use:

```js
import { frag } from 'fragtml'

const html = frag(fragmentId)
```

Calling `html('name')` directly before a template can break editor HTML highlighting because the tag expression is no longer a simple identifier. Assign the result to a local tag name, or use the `/* html */` marker that Sublime Text and Zed understand:

```js
const h = frag(fragmentId)

return h/* html */`<p>${value}</p>`
```
```

--------------------------------

### Explicit Raw Insertion within Safe Tag

Source: https://github.com/bcomnes/fragtml/blob/master/plans/fragment-html-template-library.md

Illustrates using `html.raw` to insert trusted HTML content directly within a safe `html` tagged template. This allows mixing escaped and unescaped content in the same template.

```javascript
html`<div>${html.raw('<em>trusted</em>')}</div>`
// render(...) => '<div><em>trusted</em></div>'
```

--------------------------------

### Unsupported Quoted Boolean Attributes

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Demonstrates that quoted forms for boolean attributes are intentionally unsupported in v1.

```javascript
html`<button ?disabled="${loading}">Save</button>`
html`<button ?disabled='${loading}'>Save</button>`
```

--------------------------------

### html.fragment.end

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Marks the end of the most recently opened fragment range, completing the definition of a renderable fragment.

```APIDOC
## `html.fragment.end`

Ends the most recently opened fragment range.

```js
${html.fragment.end}
```
```

--------------------------------

### Direct String Coercion of HTML Results

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Illustrates that the result object from html tag can be directly coerced to a string using String() or template literals.

```javascript
const result = html`<p>${'Hello'}</p>`

String(result)
result.toString()
`${result}`
```

--------------------------------

### Boolean Attributes

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Supports toggling boolean attributes in HTML elements using unquoted syntax, like `?name=${condition}`.

```APIDOC
## Boolean attributes

Use unquoted `?name=${condition}` syntax to toggle a boolean attribute.

```js
html`<button ?disabled=${loading}>Save</button>`
```
```

--------------------------------

### Type Guards

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Provides public type guard functions to safely check the type of values, such as `isFragmentBoundary`, `isHtmlResult`, and `isRawHtml`.

```APIDOC
## Type guards

Use the public type guards to narrow unknown values without importing from internal `lib/` paths:

```js
import {
  isFragmentBoundary,
  isHtmlResult,
  isRawHtml
} from 'fragtml'
```
```

--------------------------------

### Derive Full Argument Type for Template Implementation

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Derives the full argument type for the shared template implementation using FragmentTemplateArgs.

```typescript
type PageTemplateArgs = FragmentTemplateArgs<PageArgs>

// Equivalent to:
// {
//   fragmentId?: 'inner' | 'outer' | undefined
//   context: {
//     foo?: string
//     title?: string
//     text?: string
//   }
// }
```

--------------------------------

### Check if a Value is a RawHtml Instance

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Verifies if a given variable is an instance of the `RawHtml` class, which is returned by `raw(value)` and `html.raw(value)`.

```javascript
import { RawHtml, raw } from 'fragtml'

const trusted = raw('<strong>trusted</strong>')

trusted instanceof RawHtml
```

--------------------------------

### TypeScript with Explicit Fragment-Name Union

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

This TypeScript snippet demonstrates how to use explicit fragment-name unions for type-checking fragment IDs and declared boundaries. It defines a `ContactFragment` type and uses it with `frag` and `RenderOptions`.

```typescript
import { frag, render } from 'fragtml'
import type { RenderOptions } from 'fragtml/types.js'

type ContactFragment = 'archive-ui' | 'details'

function contactDetailTemplate ({ 
  contact,
  fragmentId
}: { 
  contact: Contact
} & RenderOptions<ContactFragment>) {
  const html = frag<ContactFragment>(fragmentId)

  return html`
    <article>
      <h3>${contact.name}</h3>
      <p>${contact.email}</p>

      <div hx-target="this">
        ${html.fragment.start('archive-ui')}
        <button>${contact.archived ? 'Unarchive' : 'Archive'}</button>
        ${html.fragment.end}
      </div>
    </article>
  `
}

export function contactDetail (args: {
  contact: Contact
} & RenderOptions<ContactFragment>) {
  return render(contactDetailTemplate(args))
}
```

--------------------------------

### Handling Non-Printing Values

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Illustrates that null, undefined, booleans, and NaN values are omitted during interpolation, while 0 is rendered.

```javascript
render(html`<p>${null}${false}${Number.NaN}${0}</p>`)
// '<p>0</p>'
```

--------------------------------

### Check if a Value is an HtmlResult Instance

Source: https://github.com/bcomnes/fragtml/blob/master/README.md

Verifies if a given variable is an instance of the `HtmlResult` class, which is returned by `html` and `frag` tagged templates.

```javascript
import html, { HtmlResult } from 'fragtml'

const result = html`<p>Hello</p>`

result instanceof HtmlResult
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.