Views kit

The views kit adds focused screens beyond CRUD: boards, calendars, plans, large tables, trees, maps, writing, collaboration, files, settings and common app states. The implemented engine helpers are framework-free; Svelte components live in separate lazy subpaths. Some engine subpaths reserve planned names but have no runtime exports yet. Import a view from a lazy route so unused views add nothing to initial JavaScript. See the detailed component and engine references in `@protoyard/views-ui` and `@protoyard/views`.

Choose a view

To run a whole blueprint-described app rather than one view, use BlueprintApp from @protoyard/crud/app. It wires the blueprint screen kinds (board, calendar, timeline, map, analytics, dashboard, settings and tabbed detail) to the routes of the shared app model, and loads each kit lazily through the screen-kind registry. See the crud README.

Each package exposes one entry per subpath; neither package is re-exported by @protoyard/ui. @protoyard/views root is types-only. views-ui views may share lib/ and states/; static imports between view folders are guarded. The files view reuses the tree view through its declared dependency. Dynamic imports can load another view subpath only when needed. More detail is in the component reference.

Data and mutations

Pass a reactive query (often from liveQuery) and accessors or display callbacks appropriate to the view. Components own transient interaction state; they do not write database tables. Read-only views remain read-only when a mutation callback is absent. Mutation callbacks should invoke the prototype's service, which enforces the full boundary:

UI callback → service → session.assert → zod validation → environment.run → db.transaction

For example, BoardView calls onMove(move, item), CalendarView calls onChange(change) / onCreate(slot), TimelineView calls its schedule change callback, and DataGrid calls onCommit(row, key, value). Services must revalidate invariants such as hard WIP limits, dependency acyclicity, and permission to edit. Async callbacks show pending feedback; failed optimistic moves roll back and announce the error. Read and write contracts for each component are in the package reference linked above.

For comment mentions, services use mentionedIds(body) from the activity engine to create recipient-scoped notification rows in the same transaction as the comment; the UI does not infer or send notifications itself.

The deterministic @protoyard/views/scenarios engine provides fragments via viewsFragments.<kit>(level) for calendar, plan, geo, tree, files, social, and related views. Levels are empty, typical, dense and edge. Generators use the scenario context (ctx.rng, ctx.faker, ctx.ids, ctx.time); pass runtime clock and persona locale/time zone into the UI rather than reading the system clock. The engine README documents each generator and its integrity checks.

Keyboard and phone behavior

The component reference has each view's full shortcut list and callback behavior. These views respect reduced-motion preferences where they animate.

Bundle measurements

All views are lazy-route candidates, so the initial JavaScript cost is 0 KB when the first route does not import them. Task 117 measured isolated Vite builds over a realistic Protoyard shell (Svelte, renderer, UI, services and runtime dependencies), gzip -9, on an M1 Max. These are the enforced view chunk figures; the table gives before/after for the overlay-lazy-loading change and its current ceiling:

The other components have per-component gzip measurements in the views-ui README; those figures use a component-focused esbuild probe with framework and shared packages external, so compare them only within that method. The real-build guard is pnpm vitest run packages/cli/tests/views-bundle.test.ts; it verifies the isolated ceilings, lazy overlay chunks, and that unused sibling views are shaken out. Current known gaps: grid and calendar exceed the plan's tighter 16 KB and 12 KB aims respectively while remaining below enforced ceilings; keel task detail downloads 74.7 KB with comments/editor; and first overlay use may fetch a small chunk. Details and methods are in `PERFORMANCE.md`.

Honest limits

• The map draws a fictional Port Meridian SVG city. It has no real geography,

map tiles, geocoding or runtime network access.

• Calendar recurrence implements a documented RFC 5545 subset, not every

RRULE field. See the calendar engine reference for supported fields.

• The 100,000-row grid measurement uses generated in-memory rows to measure

rendering and virtualization. Typical IndexedDB prototype worlds are much smaller; the benchmark is not an IndexedDB throughput claim.

• The editor is a textarea-based Markdown editor, not a WYSIWYG editor. Its

preview renders a safe syntax tree as elements and never injects HTML.

• These packages provide simulated prototype behavior. They are not a

production calendar, geographic information system, file backend or collaborative service.

Verify the views kit

Run from the repository root:

pnpm vitest run packages/views packages/views-ui
pnpm --filter @protoyard/views typecheck
pnpm --filter @protoyard/views-ui typecheck
pnpm vitest run packages/cli/tests/views-bundle.test.ts
pnpm exec tsx scripts/bench-grid.ts --rows 100000 --runs 3 --check

The browser E2E row for this surface is in the testing guide and is run by the lead during integration.

For agents

The distributable Protoyard skill routes kit choices through its kits sub-skill (`skills/protoyard/kits/SKILL.md`) and its catalog (`skills/protoyard/references/kits.md`), which link back to this guide. Keep the catalog's entry for this kit in step when its entry points or limits change.