Changelog

Every release of @noctcore/showcase-kit, newest first, generated from CHANGELOG.md. The kit follows semantic versioning. Until 1.0, a minor release (0.2.0 to 0.3.0) adds features and can also change how existing options work, while a patch release only fixes. An entry that needs action from you when you upgrade carries a callout.

Follow new releases with the Atom feed, on GitHub releases or in the npm version list.

0.3.0

Released 2026-09-27npmtag v0.3.0changes since 0.2.0

Minor changes

New features. Before 1.0 a minor release can also change how existing options work; an entry that needs action from you carries a callout.

• #12 dcbeac8 More looks for the hero, the frames and the README snippet. Every new option defaults to the look you have today, so an existing config renders the same images byte for byte.

  • Hero layouts: hero.layout picks the composition: stack (the default, as before), spotlight (one large straight window running off the edges), split (one window in perspective), row (up to four windows under centered text), mosaic (a tilted wall of windows) and centered (text first, one window rising from the bottom). hero.shots takes as many shots as the layout shows and defaults to that many of the first shots.
  • Frame styles: frame.style also takes browser (a toolbar with an address bar, whose text is the new frame.address, '{url}' by default), windows (a Windows title bar) and terminal (a terminal tab; in tty mode the bar takes the terminal background). tty mode refuses browser, and cdp mode needs an address without {url}.
  • Backgrounds: frame.background and hero.background also take { type: 'mesh', colors }, { type: 'dots', color, dot, spacing } and { type: 'noise', from, to, angle, amount }, a gradient with a film grain that is the same on every run.
  • README layouts: showcase readme --layout <name> prints table (the default, as before), rows, featured, details or list, all built from HTML that GitHub keeps in a README. --cols applies to table and featured. The library’s readmeSnippet takes the same layout option.

Patch changes

Fixes and small improvements that need no change on your side.

• #9 cbe7e61 Terminal apps: a shot no longer catches a frame the app is still drawing. A terminal can hand one write over in pieces (a macOS pty passes 1024 bytes at a time), so the waitFor text could be on screen before the rest of its frame, and the shot came out cut off, with different bytes from run to run. Before every shot the kit now waits until the screen has not changed for 100 ms, which adds about 100 ms to each shot. An app that redraws the same frame on a timer settles at once. An app whose screen never stops changing (a clock, a spinner) is shot after at most 1 s, or sooner when the shot’s timeouts.shotMs runs out, with a warning; give it a frozen mode for captures, as the terminal determinism guide describes. Trailing separators in a CDP url, outputs.portfolio and shim arguments are now trimmed in linear time, with the same results as before.

0.2.0

Released 2026-09-26npmtag v0.2.0changes since 0.1.1

Minor changes

New features. Before 1.0 a minor release can also change how existing options work; an entry that needs action from you carries a callout.

• 33abe38 In url mode, a nav path that starts with / ('/docs/', or { goto: '/docs/' }) now resolves under the target url’s path instead of its origin: with url: 'https://x.io/app/' or 'https://x.io/app' it visits https://x.io/app/docs/. Configs that worked around this by repeating the base path ('/app/docs/' with url: 'https://x.io/app/') should drop the prefix. The base directory is the url’s path; a last segment with a dot names a file and is dropped, like a relative link, so with url: 'http://localhost:5173/index.html', '/about' visits http://localhost:5173/about. A trailing slash always means a directory (https://x.io/v1.2/). “Starts with /” is read the way the url parser reads it: a goto that starts with a backslash ('\docs'), or with a slash or backslash after leading spaces, tabs or control characters (' /docs'), gets the same rule. So do protocol-relative spellings ('//host/x', '\\host/x', ' //host/x'): they no longer visit another host but stay on the target origin (https://x.io/app//host/x). Every other goto resolves exactly as in 0.1.1, with new URL(goto, url): '#/settings' and '?tab=2' keep the url’s file (http://h/app/index.html#/settings), 'docs/' and '../x' resolve from the url as written, 'https://other.dev/x' is left alone, and a scheme with a relative path is relative when it matches the url’s scheme ('https:docs' with url: 'https://x.io/app/' visits https://x.io/app/docs). With a url at the origin root (http://localhost:5173), a root-relative path such as '/about' visits the same page as before.

  Warning

  A url-mode config that repeats the url’s base path in a nav path ('/app/docs/' or { goto: '/app/docs/' } with url: 'https://x.io/app/') now visits https://x.io/app/app/docs/. Drop the prefix and write '/docs/'.

• 3274ec3 New outputs.readme: false for portfolio-only configs (frame and all skip the README images; portfolio and hero still render from the raw captures) and outputs.portfolio.gallery: false | '<path>.json' to skip or relocate showcase.gallery.json, for example out of a web root. PortfolioResult.galleryFile is now undefined when the gallery is skipped.

  Note

  TypeScript: ResolvedConfig’s outputs.readme is now string | false and PortfolioResult.galleryFile is string | undefined, so code that uses either as a string stops compiling until it handles the new case.

• 07f120a Terminal clips: a tty config can list clips, short animated recordings that showcase record (and showcase all) writes to outputs.clips (default assets/showcase/{lang}/{id}.{ext}). Each clip starts a fresh app and runs its steps ({ keys }, { type, delayMs? }, { waitFor }, { sleep }) on the kit’s own frame clock at fps (default 10), merges frames that did not change, and is framed like the README images with one frame render per clip. It ends tailMs (default 1500) after the last step, at durationMs (default 60000) or at maxFrames (default 300 frames after merging, each held in memory until the clip is encoded), whichever comes first; the last two warn and still write what was recorded. The app may exit during the tail (a CLI that prints and exits, or a last step that quits it), which ends the clip on its last screen; exiting before the steps are done fails the clip. Most TUIs clear the screen when they quit, so leave the quit key out of the steps: the kit quits the app with quitKey after the tail. Formats default to lossless animated WebP plus GIF; 'mp4' is opt-in and needs ffmpeg on PATH. showcase readme lists clips after the shots, and says why instead of printing an empty table when outputs.readme is false and --only names only shots. Clips in url and cdp mode are refused until web clips arrive in v0.3. New exports: record and encodeAnimation (frames plus delays in, WebP, GIF or MP4 out). encodeAnimation refuses input it cannot encode with a ShowcaseError and splits a delay longer than sharp’s 65535 ms per frame into repeats that add up to it. For MP4, ffmpeg is looked up in absolute PATH entries only, Ctrl+C stops it and removes its temporary folder, and an encode that runs over 5 minutes is stopped with an error.

• 1d571fa Terminal apps: target.mode: 'tty' runs a TUI or CLI in a pseudo terminal and captures its screen into the same raw, framed, portfolio, hero and README outputs as web apps. Shots press keys (or run a nav function with the terminal session), wait for waitFor text and can restart the app; ready is text on screen; a new terminal block sets the theme, font, line height, padding and cursor, with JetBrains Mono bundled. Web-only keys (viewport, colorScheme, css) are rejected in tty mode and tty-only keys in url and cdp mode. showcase init --tty writes a starter config. Needs @lydell/node-pty (or node-pty) as an optional peer and Node, not the Bun runtime. The terminal engine is exported for scripts: openTtySession, renderTtyScreen, resolveTerminalOptions, parseKeys, DARK_THEME, LIGHT_THEME and TERMINAL_DEFAULTS.

  Types: ShowcaseConfig is now WebConfig or TtyConfig (defineConfig picks one from target.mode), and ResolvedConfig is ResolvedWebConfig | ResolvedTtyConfig; narrow with isTtyConfig(config) before reading web-only fields such as viewport.

  Important

  TypeScript: code that reads a web-only field (viewport, colorScheme, css) from a ResolvedConfig, for example the result of loadConfig, stops compiling. Narrow it first: if (!isTtyConfig(config)) { ... }. A config file for url or cdp mode written with defineConfig needs no change.

Patch changes

Fixes and small improvements that need no change on your side.

• 67be194 Terminal apps: target.inheritEnv controls which of your environment variables the app gets (true by default; false or a list of names keeps tokens and home paths out of an app whose screen becomes a committed image, while PATH and on Windows PATHEXT, SystemRoot and ComSpec are still inherited so it can start). A CLI that prints its screen and exits at once is now captured instead of failing with “exited before”. Arguments passed through a Windows .cmd or .bat shim that contain " or % are refused with a clear error (cmd.exe cannot pass them), and trailing backslashes arrive intact. renderTtyScreen checks the theme of the look it is given. openTtySession returns before Windows reports the app’s PID, so Ctrl+C requests the terminal’s teardown even that early.

0.1.1

Released 2026-09-24npmtag v0.1.1changes since 0.1.0

Patch changes

Fixes and small improvements that need no change on your side.

• f39d6b3 Stopping a started command on Linux and macOS no longer waits the full two second grace period and then sends a needless SIGKILL: it now returns as soon as the process tree has exited on SIGTERM. When the host exits without calling stop(), the process group is killed with SIGKILL right away instead of blocking the exit for two seconds.

0.1.0

Released 2026-09-24npmtag @noctcore/showcase-kit@0.1.0

Minor changes

New features. Before 1.0 a minor release can also change how existing options work; an entry that needs action from you carries a callout.

• First release: the showcase CLI and a typed config API that capture an app’s views (url mode in headless Chromium, or cdp mode for Electron and WebView2), frame them into README images, export exact-size 16:9 portfolio images with a gallery JSON, print a README image table, render a hero banner, and generate web, Electron and Tauri icon sets.