v4.2.0

Byline 4.2 is the blocks and uploads release. Blocks gain the same schema/admin split that collections have had since the beginning — plus a dedicated code field — and the upload pipeline gains declarative storage locations and human-friendly storage keys.

📖 Blocks reference: the new Blocks doc covers the full architecture; docs/04-collections/ was renumbered to make room for it.

Highlights

• @byline/core / @byline/admin — per-block admin config. defineBlockAdmin(block, { fields }) pairs a React-carrying admin config with the React-free defineBlock() schema, registered site-wide on ClientConfig.blockAdmin and keyed by blockType — one entry applies wherever the block renders (any collection, any nesting), matching how codegen already dedupes block contracts across collections. Block child fields can now take per-field editor and components overrides — previously they could only inherit the global richtext editor registration. Boot validation rejects unknown blockTypes, duplicates, and field keys that aren't top-level fields of the block. The reference app demonstrates the payoff: the QuoteBlock's quotation renders a minimal non-AI editor and the PhotoBlock's caption a minimal-with-links editor, while the site-wide AI editor stays registered for everything else.

• @byline/core / @byline/admin — dedicated type: 'code' field. Stores a plain string in the existing text store (no migration); the admin widget is a lazily-loaded CodeMirror 6 editor that stays out of the main admin chunk, with per-language grammars loading on demand and light/dark theming driven entirely by CSS custom properties (--byline-code-*). language sets a static highlight language; languageField binds highlighting to a sibling select at runtime — switching the select re-highlights live. Declared minLength/maxLength are enforced; code bodies are deliberately excluded from full-text search indexing and export as fenced blocks in the markdown surface. The reference CodeBlock is the worked example.

• @byline/core / @byline/storage-local / @byline/storage-s3 — upload.location: a declarative storage-key scope per upload field (upload: { location: 'publications/covers' }, nested segments allowed) replacing the <collectionPath>/ default, so multiple upload fields on one collection no longer mix objects in one directory. Plain isomorphic-safe data, boot-validated (POSIX segments, no ..), folded into the collection fingerprint. Precedence: beforeStore { storagePath } (verbatim, unchanged) → location → collection default — hooks remain the tool for dynamic keys.

• @byline/storage-local / @byline/storage-s3 / @byline/core — friendly upload storage keys. New uploads land at <location|collection>/<slugified-base>-<suffix>.<ext> (e.g. events/meeting-agenda-4fa35g.pdf) instead of <collection>/<uuid>-<filename> — the filename leads and a short 6-char base36 suffix rides before the extension, so downloads, object-store consoles, and logs show human-readable names. Providers verify each candidate key is free (exists()) and retry on collision, falling back to a full-entropy UUID suffix after three straight collisions — collision safety is preserved, not traded away. The base name is slugified by a new installation-wide ServerConfig.uploads.filenameSlugifier (the upload parallel of the path slugifier; default slugifyFilename exported from @byline/core). No action required: existing stored objects keep their recorded paths; the new layout applies to new uploads only.

• @byline/core / @byline/admin — itemViewSort on CollectionAdminConfig: orders the relation picker independently of the list view's defaultSort (e.g. a media library newest-first in its list but alphabetical in the picker). Same { field, direction } shape and boot validation as defaultSort; rejected on orderable: true collections, whose manual drag order owns the picker too.

• @byline/admin / @byline/i18n — admin editor UX: the blocks and array add-rows gained localized, clickable text labels (new fields.blocks.addBlock / fields.array.addItem strings in all seven interface locales) with hover affordance; the block-picker modal is height-capped responsively (80/70/60 dvh) with its card grid scrolling; assorted select/text/checkbox widget polish.

Bug Fixes

• monorepo — the byline:generate / byline:generate:check turbo tasks now also depend on @byline/richtext-lexical#build: block and field schemas may import the editor-config seam from @byline/richtext-lexical/server, which previously failed on cold CI runners before that package had built.

Chores

• monorepo — docs/04-collections/ renumbered (blocks=02 through collection-versioning=08) with all cross-references updated repo-wide; the uploads doc gained quick-reference entries for upload.location and the filename slugifier; the reference app added worked examples for two-sided custom richtext field presets (minimal editor helpers).

All other @byline/* packages bumped to 4.2.0 in lockstep with no behavioural changes this cycle.