Talk to us
Editor SDKOverviewPlaygroundPresentationBlocksshadcnFor authors
Dollie Editor SDK
Playground

Dollie Editor SDK guide

CLI

Current Dollie Editor command reference.

Run commands through the locally installed package:

npx dollie-editor <command>
Command Purpose
info [--json] Inspect the project and discovered catalogs
add <package> Install a catalog package and rediscover catalogs
discover Regenerate the discovered catalog module
fields <path> Generate fields for one component
fields --dir <dir> --out <file> Generate a catalog fields module
build Build configured registry items
export Export a page template
import Import and validate a page template
recommend <proposal.md> Rank existing sections and compatible illustrations with Jev through OpenRouter

Recommend sections and illustrations

Run from a host with a configured x-dollie-editor manifest. Refresh that manifest first, just as for catalog queries:

npx dollie-editor recommend ./proposal.md --surface landing --output ./page-plan.json

The local CLI reads OPENROUTER_API_KEY from the process environment, or from the host's .env file. --env-file <path> selects another local dotenv file; an exported key takes precedence. Only the OpenRouter key is consumed. The CLI does not evaluate shell expressions, copy credentials, or include environment values in the proposal state or output. Dotenv loading requires Node 20.12+. TypeSafe must be enabled in the account's OpenRouter provider settings.

The command calls the OpenRouter Decisions API with typesafe/jev-1.13 by default. Use --model <id> to select another compatible Jev decision model. Only running recommend loads this integration; the editor runtime does not require an AI provider or new dependency.

Input and selection

Supply UTF-8 Markdown (.md/.markdown) or plain text (.txt), up to 24 KB. For Markdown, the shallowest headings at level 2 or deeper delimit story beats; nested headings remain within their parent beat. Multiple level-1 headings are also supported. A document without section headings is one beat.

A heading named Landing page proposal, Page proposal, Landing page copy, or Page copy is automatically treated as the story container: its children become beats, and surrounding planning notes remain context only. Use --under "Heading title" to select another container, or --heading-level 3 to explicitly choose a beat level. At most 30 beats are accepted. Fenced code and frontmatter headings do not create beats. Check the interpretation before paying for inference:

npx dollie-editor recommend ./proposal.md --dry-run
npx dollie-editor recommend ./proposal.md --under "Our story" --heading-level 3

Use --section-count 6 to cap a run to the first six selected beats. This keeps the recommendation and generation budget bounded when a proposal contains more copy beats than the page should contain.

The complete document is sent as context alongside each current beat. All eligible sections are scored for narrative purpose, supplied content, density, and field constraints. Deprecated and non-authorable sections are excluded. For each shortlisted section, the CLI scores the available illustrations for each accepting slot, using the illustration description, size, and placement guidance. Image-only slots never receive illustrations. No keyword shortlist silently removes candidates. Independent beats and slots share a rolling request queue with at most 16 requests in flight. Batches contain up to 6 candidates, reduced automatically to fit the request-size budget. --concurrency <1-32> and --batch-size <1-64> let hosts tune these limits for their provider account. Larger batches change the candidate context seen by the model and can change rankings substantially; evaluate quality before increasing the default. Output retains source order even when requests complete out of order. A failure stops queued work and waits for in-flight requests before returning an error.

--catalog <id> restricts sections, and --illustration-catalog <id> restricts illustrations separately, so shared layouts can use a host's own brand assets:

npx dollie-editor recommend ./proposal.md \
  --catalog shared-website-sections \
  --illustration-catalog dollie-assets \
  --top 3 --output ./page-plan.json

Output

The JSON plan contains ordered source spans, a selected section ID for each beat, ranked section alternatives with field contracts, and ranked illustration IDs for each accepting slot. --top controls both lists (1–5, default 3). Array slot paths such as items[].illustration describe candidate pools; assign visuals to individual items when composing the page.

Scores run from 0 (unusable) to 3 (excellent fit). --min-score defaults to 2; this is an initial, uncalibrated threshold, not a correctness guarantee. Unmatched beats and slots have status: "no-match" and selected: null. Rejected section candidates remain available for diagnosis when no section meets the threshold. Confidence and distributions are retained separately.

Plans also include source/manifest hashes, the requested and resolved models, request count, elapsed time, and provider-reported usage/cost. The performance object reports the execution limits, peak concurrency, and median/p95 request duration (network plus provider time, excluding local queue wait). Unavailable usage is null, never an inferred zero. Output goes to stdout, with progress on stderr, or to a new --output file. Existing files are never overwritten.

This is not a complete production PageConfig: it does not generate copy, choose image-library assets, fill every card, save drafts, or publish. Composition and visual review remain subsequent steps. A failure exits nonzero without writing a partial plan. --cwd and --manifest work as in catalogue discovery.

To get a renderable frame in the same run, pass the host's running preview server:

npx dollie-editor recommend ./proposal.md \
  --server http://127.0.0.1:5188 --preview \
  --output ./page-plan.json

The output then includes page, a minimal PageConfig containing the selected sections and any selected illustration slots that have simple paths, plus preview.url, the normal SDK preview link. Array slots such as items[].illustration remain in the recommendation metadata because they need per-item copy/content assignment; they are not guessed into the PageConfig. The temporary JSON sent to the loopback preview route is removed after the server accepts it. The preview remains ephemeral and does not save or publish a draft.

Export a Page Template

npx dollie-editor export \
  --page page.json \
  --id product-launch \
  --name "Product launch" \
  --description "A focused launch page" \
  --out templates/product-launch.json

--page accepts a bare PageConfig or a BuilderDocument containing definition. --vertical adds optional descriptive metadata. Without --out, the template JSON is written to standard output.

Check or import a Page Template

npx dollie-editor import \
  --template templates/product-launch.json \
  --manifest public/editor-manifest.json \
  --check

The command exits with status 1 when the active manifest cannot satisfy the template. Add --json for a machine-readable compatibility report.

To write the validated Page definition:

npx dollie-editor import \
  --template templates/product-launch.json \
  --manifest public/editor-manifest.json \
  --out page.json

--partial drops missing Sections and Element references. Use it only when that data loss is intentional.

The current CLI does not provide an init command. The recommended onboarding path uses the official skill and current package commands instead of documenting planned CLI behavior as available.

Local visual previews

The SDK owns dollie-editor preview section|page|illustration, the ephemeral Vite server plugin, and PreviewApp. No Website Studio runtime is required. Hosts supply their actual catalogue and CSS; the preview renders that same code.

Register previewPlugin({ entry: '/src/preview.tsx' }) from @dollie_ai/editor/preview/server in the host Vite plugins. In that entry, mount <PreviewApp catalog={catalog} /> from @dollie_ai/editor/preview with React createRoot and import the host stylesheet. To preview under more than one stylesheet, pass them as lazy imports instead and pick one with ?css=<name> (or --css <name> on any preview command); the first entry is the default:

<PreviewApp
    catalog={catalog}
    stylesheets={{
        website: () => import('../css/marketing.css'),
        frontend: () => import('../css/preview-frontend.css'),
    }}
/>
``` The plugin supplies
`/preview.html`; no separate HTML file is needed. It runs only in development.

```bash
dollie-editor preview section --file section.json --server http://127.0.0.1:5173 --width 1440
dollie-editor preview page --file page.json --server http://127.0.0.1:5173
dollie-editor preview illustration --file illustration.json --server http://127.0.0.1:5173 --width 900 --dark

Section input is { "component": "registered-id", "props": {} }; page input is PageConfig or a saved BuilderDocument; illustration input is a JSON string id or { "id": "registered-id", "props": {} }. --file - reads stdin. Use the actual host Vite URL/port. HTTPS Herd hosts may require Node's --use-system-ca to trust their locally installed certificate; do not disable TLS verification.

The command returns JSON with url, expiresInSeconds, and saved: false.

dollie-editor preview gallery prints a stable URL that renders a whole catalogue instead of one definition: every section, illustration, image and widget with its name, id, catalogue, category, feature, size, tags, description and a collapsible list of its fields, rendered with its default props. Nothing is posted and nothing expires; the page reads the filters from the URL, so the link can be bookmarked or pasted into a handover, and the sticky filter bar at the top rewrites it.

dollie-editor preview gallery --kind illustrations --catalog padelguru-assets --server http://127.0.0.1:5173
dollie-editor preview gallery --kind sections --category hero --dark
dollie-editor preview gallery --q booking --ids pg-booking-moment,pg-academy-page

--kind is all (default), sections, illustrations, images or widgets. Filters: --catalog (package id), --category, --feature, --size, --tag (search metadata tags), --q (id or name contains), --ids (comma-separated), --deprecated (include compatibility entries, hidden by default), --dark, --css <name> (a host stylesheet registered on PreviewApp). Sections stack full width, grouped by category; elements sit in a grid grouped by size, so small ones share a row and extra-large ones get the width. The same page answers directly: /preview.html?gallery=illustrations&catalog=padelguru-assets. Open that URL in the browser and inspect an actual desktop screenshot: fit, scale, crop, padding, text wrapping/density, contrast and media/copy balance. Scroll to reveal animations. Set the browser viewport to the requested desktop width when assessing responsive sections; the CLI width sets the canvas, not the browser viewport. Validation or DOM text alone is not visual approval. Describe what you saw. Mobile checks are only needed when requested.

Previews expire after one hour, on server restart, or when evicted by the 30-preview limit. Requests are limited to 2 MB and loopback connections; cross-origin writes are rejected. They never save drafts, revisions or publications. The renderer validates against the supplied catalogue and shows errors in place. It renders the supplied sections without inventing host navigation or footer.