The catalogue index is version 9 and the entry detail is version 4. Each index record lists detailId. Each detail carries detailId and no deploymentId, and a removed detail no longer carries generation. Static builds write mokly-viewer/deployment.json. @mokly/viewer exports EntryDetailV4 instead of EntryDetailV3. readCatalogueIndex reads version 9 only, and readEntryDetail reads version 4 only. Rebuild and republish every catalogue with the matching viewer. Mokly Cloud must accept index version 9.
Features
cli: show comparison steps while Changes loads (#248) (afc9f58)
dev: install and build before npm run dev serves (#250) (e9c2022)
give entry details content ids and add a deployment file (#224) (f93afce)
ui: move the controls to @mokly/ui, 2 of 5 (#251) (7edabc3)
ui: move the inspector to @mokly/ui, 3 of 5 (#253) (9f68de1)
ui: move the layout and theme to @mokly/ui, 5 of 5 (#255) (8eb2b9a)
ui: move the preview views to @mokly/ui, 4 of 5 (#254) (8c2bbff)
ui: move the shell chrome to @mokly/ui, 1 of 5 (#249) (14c6f9e)
Bug fixes
deps: select patched minimatch for lint and release tools (21c8663)
graph: carry unchanged public closures across replacements (#244) (bb33139)
Performance
render: reuse stylesheet bundles with shared module evidence (#242) (ee7d8ea)
keep a component's usage lists in its parent detail (#223)
catalogue index v8 and upload envelope v3. Viewers, hosts, and receivers that read index v7, review.json, or envelope v2 must upgrade. Mokly Cloud adopts the change in its own repository after the release.
Features
html: share one HTML driver between checks and trees (#239) (02eec93)
keep a component's usage lists in its parent detail (#223) (0a1d351)
publish: send gzip Blob bodies when the receiver lists gzip (#221) (2dd2937)
remove review.json; compare from the index and entry details (#217) (c65aaef)
ui: add the @mokly/ui shared UI package (#243) (e4c6d2c)
warn on stylesheet renderer seeds and align the docs (#218) (89c12ef)
Bug fixes
config: give config-relative paths one normalized form (#240) (843ac8b)
css: align CSS Modules scanners with cssparser (user item 111 C) (#241) (c9d402c)
deps: update pulldown-cmark to 0.13.5 (#230) (9f78200)
git: read unreadable extraction files through Git (#237) (3ea78c0)
graph: key unattributed definitions and unnamed previews exactly (#235) (c92c1a7)
graph: report closure warnings in Serve and previews (finding 1) (89c12ef)
postcss: keep the paths of hook-supplied modules (#238) (10dd5a0)
verification: name the right command in two errors (finding 5) (89c12ef)
Performance
build: capture head documents once during the build check (#220) (a9dd1e8)
compare: read base files from the leased extraction (#236) (aab537b)
git: convert base batches in one Git process, time the extraction (#229) (d4c6f6a)
graph: bundle stylesheet roots in parallel (#228) (c83becc)
per-entry render keys and cross-side render reuse (#227) (9ce7585)
serve: render the background pass in bounded batches (#225) (9c56286)
The mokly CLI is a native Rust binary. @mokly/mokly selects it from the matching @mokly/native-{target} package for Linux x64 or ARM64 with glibc 2.28 or newer, macOS 11.0 or newer on x64 or ARM64, or Windows x64. There is no JavaScript CLI fallback, so keep optional dependencies enabled during installation. Mokly supports Node 22.15.0 and later 22.x releases, and Node 24.0.0 and later except 24.14 through 24.18. Node 23 is not supported. The upgrade guide gives all upgrade steps.
Use serve to browse with watch enabled by default. Use build to validate, render every view, and write a static site. Use publish to build a private site and upload it. check, export, and review are removed. Run mokly build --strict --out {temporary-directory} to validate, and replace export --out with build --out. build --watch and serve --build are removed. Use serve for development.
The configuration is the data-only file mokly.config.json, and --config names another JSON file. TypeScript and JavaScript configuration, defineConfig, componentStylesheets, ModuleResolutionConfig, ReviewConfig, StylesheetRule, WatchAction, WatchConfig, and WatchRule are removed. Paths resolve from the configuration file. $componentStylesheets is the only stylesheet token. Brace alternatives such as {a,b} replace extglob matches. Use the shipped config.schema.json for editor checks.
No command writes generated output into the repository. Remove committed mokly-generated/ output and .mokly-cache. build writes mokly-static/ by default, and Git must ignore it. Comparisons render both sides from sources with the installed Mokly version, and a base whose sources fail current validation makes Changes unavailable. serve, build, and publish accept --base. There is no committed baseline. Use movedFrom to identify an entry that moved with content changes.
Every screen and component has its own props and optional variants. defineScreen and defineComponent use render(props, context). Each export contributes one definition, so array exports fail. A Storybook file contributes one component, with its stories as variants. argTypes gives control hints only. definePage returns one complete document. Prop schemas use a strict JSON Schema 2020-12 profile with closed objects. ComponentEntryDefinition, ComponentProps, ComponentRenderContext, ComponentVariant, ComponentVariantDefinition, RegisteredComponent, and RegistryDefinition are removed.
@mokly/viewer/server, @mokly/viewer/runtime, renderViewer, shell hydration, and embedded bootstrap data are removed. MoklyViewer takes index and detail sources, and readCatalogueIndex and readEntryDetail replace readCatalogue. Catalogues use index v7 and entry detail v2, review results v8, change snapshots v4, and the live descriptor v3, and each reader accepts one version. @mokly/viewer/data exports only the path functions, the directory names, the path and link grammar, and the prop schema validators. Import ColorScheme, Viewport, MoklyVersionError, resolveInstance, and InstanceResolution from @mokly/viewer. The viewer now shares the CLI version. Rebuild every published catalogue. Mokly Cloud resets and republishes with the matching viewer, and the upload exchange stays v1.
Features
author screens and components as HTML with YAML front matter (#199) (d935e6a)
read the configuration from mokly.config.json (#199) (d935e6a)
rebuild the Mokly backend as a Rust core (#199) (d935e6a)
render comparisons from sources without generated output (#199) (d935e6a)
render the Browse shell in the browser from catalogue index v7 (#199) (d935e6a)
replace check, export, and review with serve, build, and publish (#199) (d935e6a)
use one props and variants model for every entry kind (#199) (d935e6a)
Use serve to browse with watch enabled by default. Use build to validate, render every view, and write a static site. publish builds a private site and uploads it. check, export, and review are absent. For validation, run mokly build --strict --out {temporary-directory}. Replace export --out with build --out. build --watch and serve --build are absent; use watched Serve for development.
Configuration is data-only mokly.config.json. --config names another JSON file. TypeScript and JavaScript configuration and defineConfig are absent. Use the shipped config.schema.json for editor checks. Filesystem paths are relative to the configuration file. $componentStylesheets is the only stylesheet token. Replace the componentStylesheets JavaScript export with this token in the JSON stylesheet list. WatchConfig and ReviewConfig are removed configuration types. Replace extglob stylesheet matches such as @(a|b) with brace alternatives such as {a,b}. Unsupported extglob matchers emit a stylesheet-extglob configuration warning that names the pattern and suggests brace alternatives. --strict fails on this warning under the normal build-warning policy. Replace flat generated-filename matches with entry routes such as product/**/index.html. Local stylesheet paths resolve from the JSON file. Remove .css: "text" loader overrides. Import CSS normally so the core delivers its stylesheet and referenced assets.
Do not commit generated output. build defaults to mokly-static/, which must be ignored by Git. Remove committed mokly-generated/ output and .mokly-cache. Serve and comparisons render in memory. Base extraction and dependency caches use the operating system's cache directory.
serve, build, and publish accept --base. build and publish accept --no-changes. Publish has no --out; it names its private build directory before building and keeps it after a failed upload. Publish requires a clean, committed checkout. Static output requires an empty directory or its valid ownership marker.
build fingerprints only what the build uses: the configuration, root membership, inventoried sources, and the files that rendering reaches. An edit to an unrelated repository file does not stop a build. Some edits made while a build runs are not detected. These are edits to JavaScript modules that Mokly bundles from node_modules, to files under node_modules that a PostCSS plugin reports, to .gitignore or the Git index, to ancestor tsconfig.json files, to ancestor package.json files that PostCSS module resolution does not name, to missing resolution candidates, to the file list of a directory that a PostCSS plugin reports, to files that a PostCSS plugin reads without reporting them, and to files that render callbacks read without an import. These include an installed stylesheet that a PostCSS plugin inlines. Edits to installed stylesheets that Mokly resolves itself, their url() assets, the package.json files that this resolution reads, PostCSS plugin modules, and the package manifests that PostCSS module resolution names stop the build. A PostCSS plugin can also read a file that it reports in a way that Mokly cannot observe, such as through a native addon. For a reported repository file outside node_modules, Mokly records its digest after the read and does not detect an edit between the two. Such output is consistent but stale. Build again after such an edit. publish checks the repository status again before upload and rejects an edit to any file that Git does not ignore.
Entry dependencies, component ownedDependencies and review.sharedImpact have no effect. Mokly warns and ignores them, and a --strict command fails on these warnings. Delete them, and declare component CSS with the component's stylesheets field.
Generated output uses manifest v10, catalogue read model v6 and review result v7. Rebuild and commit mokly-generated/ output that 0.14.0 or earlier wrote, and regenerate exports. A comparison base that 0.14.0 or earlier built shows Changes as unavailable until the base includes this version. Hosts that embed the viewer need @mokly/viewer 0.6.0 to read catalogues from this release.
Rename ManifestV9, ReviewResultV6 and ScreenReviewV6 to ManifestV10, ReviewResultV7 and ScreenReviewV7. MoklyVersionError.boundary can now be "review".
Features
classify each changed CSS rule by the elements that it matches (#179) (34e4bb0)
declare component CSS with the stylesheets field (#179) (34e4bb0)
move generated output to manifest v10, catalogue read model v6 and review result v7 (#179) (34e4bb0)
release: repair release evidence and manual complete retries (#183) (a0e1219)
server: keep authored files readable across reloads and restarts (#185) (a90badb)
xtask: warn on stuck boxes after suites (#181) (1086732)
Dependencies
The following workspace dependencies were updated * dependencies * @mokly/viewer bumped from 0.5.0 to 0.6.0
Upgrade Notes
Replace entries and entriesDir with roots; omit it for the default specs root, or list { dir, files?, path?, transparent? } objects.
Remove id and navPath from every definition. Move each file to the directory that should be its folder, or declare path. Rename the file, or declare slug, when the leaf should differ from the file name; declare slug: "index" or name the file index.mockup.tsx for a folder's own page.
Replace defineRoot, folder, nested screen, and nested page with directories and defineFolder records or _folder.json files for titles and order.
Give every variant a slug instead of an id; variantOf is derived.
Replace useCaseIds with useCasePaths and step screenId with screenPath, using complete or relative paths.
Export definitions from any export, default or named; mockups is no longer required.
Replace mockLink("<id>") and to="<id>" with a complete path, a relative path, or an imported definition. Raw mock:<id> becomes mock:<path>.
Declare movedFrom on an entry whose path changed together with its content so Changes pairs it with its baseline.
publish: mokly publish now requires a clean checkout. Commit, stash or ignore uncommitted files before publishing. There is no override flag.
Use mokly-viewer/ and generations/, ownership v3 and upload v2. Older services reject publication with the documented version error until their receiver and viewer are updated.
Path identity removes id, navPath, entries and entriesDir. Use roots and file-derived paths. Rebuild manifest v8 and consume read model v4, review result v5, disclosure storage v4 and /view/<path>/ URLs. Earlier formats, URLs, ids, disclosure keys and configuration are not read or translated. The release note documents manual migration only.
Features
cache: make .mokly-cache ignore itself (#145) (43ae07b)
deps: baseline-relative audit and daily update PRs (#157) (6bb6421)
file-path identity and Markdown documents (#131) (c4138a0)
publish: require a clean checkout (#168) (acac1c7)
simplify generated output and delivery (#156) (b39d89a)
tier MockLink asChild placement and add build warnings (#124) (f66c274)
publish:mokly publish no longer uploads one catalogue archive; it runs the plan, blob and complete exchange documented in docs/protocol/mokly-upload.md, so receivers must implement that exchange. Export ownership markers are schema 2 with per-file SHA-256 digests and sizes; schema 1 markers are rejected, so export directories written by earlier releases must be removed before exporting again. Successful plain publish output is now Published Mokly catalogue. <uploaded> files uploaded, <unchanged> unchanged. or Mokly catalogue already published for this commit., optionally followed by the viewer URL line.
defineCollection, collection, and the collection types are removed; place entries with navPath or nested folder(). Generated manifests are schema v6 and the public catalogue read model is v2 (folder nodes, navPath, no collections or ancestors). Rebuild generated output after upgrading.
Features
add co-located entries and screen variants (ce3da27)
design: add the disabled and validation roles (d4228f9)
ci: gate Node 24 checks on release PRs (#114) (a8f408d)
Dependencies
The following workspace dependencies were updated * dependencies * @mokly/viewer bumped from 0.3.0 to 0.4.0
Upgrade Notes
Replace defineCollection and its CollectionInput with defineRoot and RootInput when authoring a tree, or put navPath directly on independent entries. Nesting now defines membership, so remove childIds.
Remove CollectionDefinition; folders are structure, not RegistryDefinition entries, and therefore have no id, description, or rationale of their own.
Replace collection and NestedCollectionInput with folder and NestedFolderInput. Keep title, children, and inherited metadata, but remove the former id, description, rationale, and segment fields; title is the navigation-path label.
Replace RoutedEntryInput with EntryInput, omit route, and supply navPath only when the entry belongs below folder labels. Kind and id derive the document path.
Replace catalogueViewHref with viewHref: change the arguments from (route) to (kind, id). Callers pass entry identity instead of a stored route.
Remove publicPath calls. Catalogue v3 has no public document or view path fields to validate; derive documents with entryRoute using (kind, id) and rendered views with viewRoute using (kind, id, viewport, colorScheme) when an artifact path is required.
Replace pagePreviewPath with pagePreviewMetadataPath for the metadata file inside a comparison generation, changing the argument from the complete generation-prefixed path to (id). Use snapshotPagePath with (id) for the retained page document.
Replace componentFragmentRoute with viewRoute: change the arguments from (route, variantId, viewport, colorScheme?) to ("component", variantId, viewport, colorScheme?). The component parent's route is no longer an argument because every variant is an entry.
Replace ManifestV5 with ManifestV7, ReviewResultV3 with ReviewResultV4, and ScreenReviewV3 with ScreenReviewV4. The current types use identity and view axes instead of stored artifact routes.
Replace CatalogueCollection with the kind: "folder" branch of CatalogueNode and consume folders through CatalogueReadModel.tree. Folders are structural and no longer carry collection ids, entry metadata, or childIds.
Replace CatalogueRoutedEntry with CatalogueRecord. The current union addresses catalogue records by kind and id and has no stored route.
Replace CatalogueVariant with CatalogueComponentVariant. A component variant is now a complete catalogue entry with global identity, navigation metadata, and variantOf instead of a local object inside its parent.
remove legacy configuration and exported types, automatic source discovery, comment-component expansion, legacy lint options and route aliases. Consumers must register document pages, preserve explicit routes, and regenerate v4 output through the documented ownership migration. The legacy renderer and raw HTML fixture are intentionally removed; shared change metadata replaces the removed-screen helper without removing screen support.
Features
unify catalogue pages and optional published Changes (#54) (b5065a6)