zudo-sg Docs

Type to search...

to open search from anywhere

0.4.0

Descriptor registry mode, externalPreview, and the protocol v1 preview contract for non-Preact hosts.

Released: 2026-09-27

This release lets a non-Preact host adopt the catalog, nav, search, and detail-page chrome while keeping full ownership of the preview document, and carries two behavior changes to defaults set by earlier releases. It also makes the detail page's code panel keyboard- and screen-reader-operable and requires the zdtp release that keeps the preview token panel working across SPA navigation.

Features

  • Add a second registry source, registry: { mode: "descriptor", module }: plain-data StoryDescriptor/ThumbnailDescriptor metadata in place of *.stories.tsx files with render functions, validated at build time with named, indexed error messages.

  • Add externalPreview: { url, trailingSlash? }, a host-served preview document that replaces the in-engine /components/preview route. Required in descriptor mode; optional in module mode.

  • Version the preview iframe postMessage contract as protocol v1 (v: 1, legacy messages with no v still accepted) and publish it as the framework-free leaf module @takazudo/zudo-sg/preview/messages, so an externalPreview document can implement it without depending on Preact.

  • Add routes.componentsPreview: false and routes.tokens: false opt-outs, plus an implied tokens opt-out in descriptor mode when no token manifest is configured.

  • Extend DetailWorkbench with host-controlled props (selection, theme, previewParams, sizing, toolbar) so a foreign host can drive the detail-page chrome directly instead of only reaching it through the engine's own detail route.

  • Make the code panel accessible: the variant tablist is named "Source variant", uses a roving tabindex, and moves and activates the selection with the arrow keys, Home and End. The source region is a labelled tabpanel, and both CodeMirror editors are named (Source code for {story}: {variant}, Live CSS for {story}). SourceEditor gains an optional label prop, and the regions carry stable data-sg-code-region hooks.

Bug Fixes

  • Raise the @takazudo/zdtp peer floor to ^0.8.5. It picks up the upstream fixes for a panel root left empty by an SPA remount and for a fresh mount that briefly persisted a closed state, so the preview token panel keeps working across host and engine navigation and reloads.

  • Skip preview posts from an opaque origin.

  • Reserve the external preview slug and align tokens-route detection.

  • Keep the code panel's tab selection and tabpanel labelling on the variant actually shown when the stored variant no longer matches a tab.

Breaking Changes

  • withZudoSg()'s headerTokenTrigger option now defaults to whether the preview token panel is actually wired (zdtpApplyProxy.tabsModule set), rather than defaulting to true unconditionally. A host that never wired the apply proxy's tabs module no longer gets a header button that opened nothing; setting headerTokenTrigger: true explicitly still forces it on (with a one-time console warning when the panel isn't wired).

  • A standalone DetailWorkbench (driven directly, outside the engine's own detail route) now defaults toolbar.codePanel and toolbar.tokenPanel to false. The engine's own detail route is unaffected — it opts both back in explicitly — but existing direct consumers of DetailWorkbench that relied on those controls appearing by default must now pass toolbar: { codePanel: true, tokenPanel: true }.

See Descriptor mode & external preview for the full contract and a minimal framework-free preview-frame example.