@echovisionlab/geul-common
v0.7.0
Published
Shared TypeScript contracts and helpers for Geul editors, collaboration, localized content, media blocks, pages, posts, and runtime events.
Readme
Geul common
Shared TypeScript contracts and helpers for Geul editors, collaboration, localized content, media blocks, pages, posts, and runtime events.
pnpm add @echovisionlab/geul-commonThe package exports TypeScript source. Consumers must support .ts package
exports. yjs is a peer dependency.
Validation schemas and zod locale
Exported validation schemas are zod/mini
schemas, so bundlers tree-shake them (classic zod cannot be tree-shaken).
Call parse and safeParse on them; compose them with the functional
zod/mini API (z.optional(schema), schema.check(...)) rather than classic
method chains. Parse failures throw z.core.$ZodError (not the classic
ZodError class); use z.flattenError or z.treeifyError to format issues.
Common never configures zod globally. Custom refinement messages are always
English, but built-in messages (wrong type, unknown key, too small, and so on)
come from the configured zod locale, and zod/mini installs none by default:
without one they fall back to Invalid input. Consumers that surface or log
issue messages must configure the English locale once at startup (importing
classic zod anywhere in the process also installs it):
import { config } from "zod/mini";
import en from "zod/v4/locales/en.js";
config(en());Development
corepack enable
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:coverage
pnpm package:smoke@echovisionlab/geul-proto is the contract source of truth. For coordinated
local changes, typecheck:local-contracts and test:local-contracts resolve it
from the sibling geul-event-contracts checkout.
Block Room inline content
Use reconcileBlockRoomInlineContent to set rich-text inline runs, including
their marks. It keeps the existing collaborative Y.Text handles and projects
character-level Y.Text attributes over the legacy per-run styles maps.
Deploy readers of character-level inline attributes before enabling writers.
The Web and Collab consumers use Block-room protocol version 2 to reject an
older editor before admission; the persisted canonical protobuf schema stays
unchanged.
setAIDocumentField routes whole inline content updates through this same
reconciler. setBlockRoomAtomicValue only writes catalog-declared scalar
fields; there is no generic payload-field setter for inline styles.
replaceBlockRoomCollaborativeText replaces the entire value of one
collaborative text leaf. It is intended for scalar text fields such as Page
section captions. On an inline text leaf, replacing the whole value also
removes that leaf's character-level Y.Text formatting while leaving any legacy
styles map in place. Use the inline reconciler when replacing inline text
that must retain or change marks.
Release
Release Please creates releases from main. npm publication uses GitHub
Actions trusted publishing without a repository npm token.
License
PolyForm Noncommercial 1.0.0. Commercial use requires a separate license from Echo Vision Lab. See LICENSE.md.
