Authoring
@pwfabric/authoring is the package a block author writes
against. It exports defineBlock, defineFactory and defineCapability, a
registry that turns block definitions into renderer components, and the
validators a publish or install gate can run (the engine itself does not
run them; a host’s gate does). It is Apache-2.0: what you author against is
an interface, and an interface must be free to adopt (see
Licensing).
pnpm add @pwfabric/authoring @pwfabric/contracts zod reactReact 19 is a peer dependency; zod 4 is what schemas are written in. The
package depends on @pwfabric/contracts, @pwfabric/core and
@pwfabric/runtime and re-exports everything @pwfabric/runtime exports, so a
block module needs one import.
Source: packages/authoring/package.json,
packages/authoring/src/index.ts.
The export surface
Everything below is a named export of @pwfabric/authoring.
| Group | Export | What it is |
|---|---|---|
| Block | defineBlock(options) | A frozen, typed block definition: type, name, Zod schema, defaultProps, React component |
| Block | validateBlockDefinition({ type, name }) | The gate’s field check; returns BlockDefinitionIssue[], never throws |
| Block | isCustomBlockDefinition(value) | Type guard for a definition |
| Block | createBlockInstance(definition, id, props?, children?) | A block instance with defaults merged and props parsed; throws on invalid props |
| Factory | defineFactory(options) | A frozen factory: build(config) returns blocks with generated ids |
| Factory | isFactoryDefinition(value) | Type guard for a factory |
| Factory | composeFactoryOutputs(...arrays) | Flattens several build() results into one block array |
| Factory | wrapInContainer(blocks, props?) | Wraps blocks in a container block |
| Factory | resetIdCounter() | Resets the generated-id counter (tests) |
| Capability | defineCapability() | A fluent CapabilityBuilder; re-exported from @pwfabric/contracts |
| Capability | CapabilityBuilder | The builder class itself |
| Registry | createCustomBlockRegistry() | A fresh CustomBlockRegistry |
| Registry | getCustomBlockRegistry() · resetGlobalRegistry() | A process-wide singleton registry, and its reset |
| Registry | CustomBlockRegistry | register, registerMany, get, has, list, getByCategory, types, unregister, clear, size, getComponents() |
| Registry | mergeRegistries(...registries) | A new registry with every definition; throws on a duplicate type |
| Registry | mergeWithBaseComponents(base, registry) | A component map: base spread first, the registry’s components on top |
| Validation | validateProps(props, schema) | { valid, props?, errors } from a Zod schema |
| Validation | validatePropsWithDefaults(props, schema, defaults) | Parsed props, or defaults when parsing fails |
| Validation | validateBlock(block, definition) | Checks type, props, canHaveChildren, allowedChildren |
| Validation | validateBlockTree(blocks, registry) | Walks a tree; blocks the registry does not know are skipped |
| Validation | createBlockValidator(definition) · createPropsValidator(schema) | Curried forms of the two above |
| Validation | formatValidationErrors(errors) · hasErrors(result) | [CODE] at path: message lines; a boolean |
| Validation | isBlock(value) · isBlockArray(value) | Structural guards: id, type, props |
| Types | CustomBlockOptions, CustomBlockDefinition, CustomBlockComponent, CustomBlockComponentProps, CustomBlockContext | The block shapes |
| Types | FactoryOptions, FactoryDefinition, FactoryConfig, BlockSpec, FactoryValidationResult, FactoryValidationError | The factory shapes |
| Types | ICustomBlockRegistry, BlockValidationResult, BlockValidationError, PropsValidationResult, BlockDefinitionIssue | Registry and validation shapes |
| Types | InferBlockProps<T>, InferFactoryConfig<T>, InferSchemaProps<T> | Inference helpers |
Source: packages/authoring/src/index.ts,
packages/authoring/src/registry.ts,
packages/authoring/src/validation.ts,
packages/authoring/src/types.ts.
How a block reaches a page
A page never imports your module. It reaches your block through two files that travel with the app, and both of their shapes are defined in the open engine.
1. Source. In a pwpack source tree a block is one folder:
atoms/blocks/<category>/<name>/component.tsx (the defineBlock module) with a
manifest.json beside it. An already-compiled block may ship as
atoms/blocks/<category>/<name>/bundle.mjs instead of the .tsx. The manifest is an
AtomFileManifest: id, kind: "block", version, name, state
(stable · beta · alpha · deprecated · experimental), and optional
category, description, tags, a knowledge entry and, for blocks,
definition — the block’s authoring metadata (props, defaultProps, canHaveChildren, and
optional allowedParents, icon, traits, allowedChildTraits).
2. Bundle. Publishing compiles the source into one ES module per block
type. The renderer’s loader looks for the exports Component and
definition; it also accepts a default, component or render export for
the component. A fixed list of imports stays external and is resolved by the
page’s import map: react, react/jsx-runtime, react-dom, zod,
@pwfabric/runtime (and its /data, /capability and /adapters subpaths),
@pwfabric/contracts, @pwfabric/core and @pwfabric/authoring. Anything
else a block imports is bundled into it. The list is BLOCK_HOST_IMPORTS in
packages/core/src/blocks/host-imports.ts.
3. Manifest. The app’s blocks/manifest.json is a list of
DynamicBlockDescriptor entries — blockType, moduleUrl, integrity
(SHA-256 of the bundle bytes), publisher, publisherVerified, and a
definition (name, optional icon, category, defaultProps,
canHaveChildren, propertySchema). Before evaluating a bundle the loader
fetches it, hashes it and compares; a missing or mismatching hash is a hard
failure, not a warning.
The engine defines the shapes on both sides of that step, and
@pwfabric/compiler turns a source tree into the bundle and manifest
(pwf build runs it for you; see the CLI). What the finished
files look like inside a built app, and how the runner reads them, is in
The envelope.
Source: packages/contracts/src/fabric/atom.ts
(ATOM_KIND_META.block.pathConvention, AtomFileManifest,
AtomBlockDefinitionMetadata),
packages/contracts/src/fabric/dynamic-artifact.ts
(DynamicBlockDescriptor, DynamicBlockDefinition),
packages/runtime/src/render/dynamic-block-loader.ts
(BlockModule, the export lookup order).
Rendering a block locally
None of the above is needed to see a block render in your own React tree. A
registry turns definitions into the component map the renderer takes, and the
renderer is exported by @pwfabric/runtime as BlockSurfaceRenderer (and so by
this package too):
import {
createCustomBlockRegistry,
BlockSurfaceRenderer,
} from '@pwfabric/authoring'
import { DEFAULT_BLOCK_LAYOUT } from '@pwfabric/contracts'
import { PricingCard } from './atoms/blocks/content/pricing-card/component'
const registry = createCustomBlockRegistry()
registry.register(PricingCard)
export function Preview() {
const surface = {
blocks: [
{ id: 'card-1', type: 'pricing-card', props: { title: 'Pro', price: 29, features: ['Everything'] }, layout: DEFAULT_BLOCK_LAYOUT },
],
}
return <BlockSurfaceRenderer surface={surface} components={registry.getComponents()} />
}getComponents() wraps each definition: it runs the block’s Zod schema over
the incoming props and, when parsing fails, renders with defaultProps
instead of throwing. The component receives props, blockId, children
and context, where context is narrowed to theme, viewport and
onEvent.
Source: packages/authoring/src/registry.ts
(getComponents, createBlockComponentWrapper, mapToCustomBlockContext),
packages/runtime/src/index.ts (SurfaceRenderer as BlockSurfaceRenderer),
packages/runtime/src/render/types.ts (SurfaceRendererProps.components).