@selorax/sections-library

The curated catalog of section types + blocks that ships with SeloraX. Merchants pick from this library via the editor's Browse modal when composing a content_type:'sections' page; the picked entry's HTML source is copied into the merchant's project as a regular sections/<name>.html file (where it can then be inline-edited or fully redesigned, just like any tenant-authored section).

Why a separate package

The library has three consumers (each with a slightly different need):

1. Editor (Browse modal) — needs the typed LIBRARY constant (id, name, category, description, tags) plus the raw source to copy on pick.
2. Runtime — needs the universal frame source as a built-in fallback so any page that references an unresolved frame type still renders (no broken pages when a merchant deletes their local copy).
3. CLI selorax create — seeds new projects with the frame.html file already present in sections/ so the starter template "just works".

Keeping the catalog in a standalone package — instead of duplicating sources across runtime/editor/cli — gives us a single source of truth and lets each consumer pull the pieces it needs at build time.

The 3-target sync model (frame.html)

sections/frame.html is special: it's both a library entry AND a runtime fallback AND a CLI scaffold seed. The build script keeps all three copies byte-identical:

• sections-library/sections/frame.html — canonical source
• runtime/src/builtins/frame.html — runtime fallback (T2 wiring)
• cli/templates/starter/sections/frame.html — CLI scaffold (T3 wiring)

Every bun run build rewrites the two downstream copies from the canonical source. If you need to change frame, edit the canonical file then rebuild.

Authoring a library entry

Each sections/<id>.html file is a normal SeloraX section source (the same shape as a tenant-authored sections/<name>.html), with one additional header directive on the first line of the leading HTML comment:

<!--
@library category=hero name="Hero, split 50/50" description="Headline + image" tags=hero,landing
@settings
[ … ]
@slots
[ … ]
-->
<div …>…</div>

@library keys (whitespace-separated, quote values containing spaces):

• category — one of layout / hero / features / atom / composite / cta
• name — human-readable label shown in the Browse modal
• description — short blurb (one line)
• tags — optional comma-separated tag list (for future filter/search)

The build.mjs script reads every sections/*.html, parses the @library header into metadata, and embeds the result + the full raw source into src/manifest.ts between sentinel markers. Consumers import { LIBRARY } from '@selorax/sections-library'.

Scripts

• bun run build — read sections, embed into manifest, bundle to dist/, hand-write dist/index.d.ts, sync frame.html to the two downstream copies.
• bun run test — schema/shape unit tests for the manifest.
• bun run typecheck — tsc --noEmit.
• bun run prepublishOnly — same as build; runs before npm publish.

Status

T1 (this commit) ships the scaffold + the frame entry only. The full 27-entry catalog lands across T4–T6.