Blueprint kinds

Protoyard blueprints declare a kind that selects the renderer, synthesizer, validation summary and catalog shelf. One JSON format covers four kinds (ADR-036).

This is not the registry ProjectKind (prototype, template, blueprint) in @protoyard/core. That names where a project lives; BlueprintKind names what the blueprint renders as.

The constants live in @protoyard/blueprint (the /kinds subpath holds the content-kind runtime: defineKindRuntime, createKindServices and the personas):

import {
  BLUEPRINT_KINDS, // ['app', 'deck', 'page', 'doc']
  CONTENT_KINDS,   // ['deck', 'page', 'doc']
  DEFAULT_BLUEPRINT_KIND, // 'app'
  detectBlueprintKind,
  parseAnyBlueprint, // async: loads the kind's body schema on demand
} from '@protoyard/blueprint';

formatVersion stays 1. An unknown kind fails with a friendly “needs a newer Protoyard” message. Existing app blueprints never carried kind; a missing field still means app, and share links / bp- namespaces keep their content identity (ADR-036).

Two levels

Content kinds share one kind runtime (defineKindRuntime in @protoyard/blueprint/kinds): IndexedDB stores for interactive block state and form responses, three simulated personas (presenter, audience, viewer), and a single default scenario. They do not use the app entity generator or Faker world.

The player routes by kind before loading the app shell (packages/player/src/kinds/KindApp.svelte). Generated prototypes import the same shells so behavior matches (Player, Generator).

App kind

An app blueprint describes entities, roles, screens and optional kits (SaaS, analytics, AI). It is the format every pre-kind catalog blueprint still uses.

• Schema: parseBlueprint / BlueprintSchema (app-only). Prefer

parseAnyBlueprint when the file might be any kind.

• Runtime: entity services, scenario generators, policy from roles.
• UI: list / detail / form screens and layout chrome from the CRUD kit.
• Honest limits: roles are UX, not security; data is fictional and

browser-local. See Generator, Database, Scenarios.

pnpm protoyard blueprint validate blueprints/crm.json
pnpm protoyard generate my-crm --blueprint blueprints/crm.json --dry-run

Deck kind

A deck is a bounded slide presentation of blocks.

• Body: deck object (slides with stable ids, steps, notes, layouts).
• Engine / UI: @protoyard/decks, @protoyard/decks-ui.
• Navigation: hash #/<slide-id>/<step>; keyboard, overview, presenter and

print paths are documented in Decks.

• Catalog: blueprints/decks/.
• Honest limits: speaker notes and overlays are simulation chrome; there is

no live multiplayer presenter backend.

pnpm protoyard list --kind blueprint
pnpm protoyard blueprint validate blueprints/decks/lumen-launch.json
pnpm protoyard generate lumen-deck --blueprint blueprints/decks/lumen-launch.json --dry-run

Page kind

A page is one scrolling marketing or landing document: ordered sections of blocks, optional top nav and form refs.

• Body: page (PageDocument from @protoyard/pages).
• UI: PageHost / PageApp with marketing layout chrome (Pages,

Layouts).

• Forms: public form blocks store responses through createFormServices

(simulated capabilities form:submit, form:read, form:admin). Not real auth or email delivery.

• Catalog: blueprints/pages/.
• Honest limits: one document scroll, not a multi-route website; no real

analytics or CRM pipeline.

pnpm protoyard blueprint validate blueprints/pages/tidewater-roasters-landing.json
pnpm protoyard generate tidewater --blueprint blueprints/pages/tidewater-roasters-landing.json --dry-run

Doc kind

A doc is one continuous flow of blocks (report, guide, one-pager) with an optional TOC and print preferences.

• Body: doc (DocDocument from @protoyard/pages).
• UI: DocHost / DocApp with docs layout chrome and heading TOC

(Pages).

• Print: continuous flow print CSS (not deck slide-per-page).
• Catalog: blueprints/docs/.
• Honest limits: not a full wiki or CMS; versioning and multi-author

editing are product stories you model with app kinds if needed.

pnpm protoyard blueprint validate blueprints/docs/northwind-quarterly-report.json
pnpm protoyard generate northwind-report --blueprint blueprints/docs/northwind-quarterly-report.json --dry-run

Authoring by kind

# Kind-aware brief: quick detects deck, page or doc (or pass --kind)
pnpm protoyard quick "A one-page quarterly report with charts for a fictional analytics product"

# Validate any kind (quick writes .protoyard/quick/<slug>/blueprint.json)
pnpm protoyard blueprint validate .protoyard/quick/<slug>/blueprint.json

# Plan a generated prototype
pnpm protoyard generate q3-report --blueprint .protoyard/quick/<slug>/blueprint.json --dry-run

Shared content primitives for deck/page/doc are documented in Blocks. Deck-only structure lint and layouts are in Decks and the blueprint package README.

Rendering and packages

Page and doc document helpers that wrap a body into a kind runtime without a full envelope:

import {
  definePrototypeFromPage,
  definePrototypeFromDoc,
} from '@protoyard/blueprint/kinds';

Those wrappers call defineKindRuntime. Prefer defineKindRuntime when you already have a full content blueprint (formatVersion, name, kind, body).

Catalog discovery

pnpm protoyard list --kind blueprint
pnpm protoyard list --kind template

Validation and honesty

• Untrusted input: share links, pasted JSON and ?src= files pass a bounded

loader (size, depth, stripped controls) before schema parse (Security).

• Simulated only: personas, form responses, decks presenter channels and

billing kits are prototype UX. Never describe them as production security or real multiplayer infrastructure.

• Fictional data: use .example / example.com identities in catalog and

fixtures.

• Unknown kinds: fail closed with an upgrade message; do not invent a

renderer.

• App vs content storage: apps use entity tables; content kinds use

blockStates and formResponses only. Switching kind identity changes the world namespace story — see Player storage notes.

Related guides

Commands quick reference

Documented in Development commands; common kind paths:

pnpm protoyard list --kind blueprint
pnpm protoyard blueprint validate <file>
pnpm protoyard blueprint new <file> --from-brief <brief> [--generate <slug>] [--dry-run]   # app briefs only
pnpm protoyard generate <slug> --blueprint <file> [--dry-run]
pnpm protoyard quick "<brief>"
pnpm --filter @protoyard/player dev
pnpm protoyard validate <slug> --build