v3.0.1—every VISA's got a PIN to crack

• fixes up build and unit test problems when using DFSG_BUILD.
• add NCPLANE_OPTION_VSCROLL to enable scrolling on a plane from the beginning.
• add NCPLANE_OPTION_AUTOGROW to support autogrowth of planes
  • if scrolling is enabled, autogrowth happens down
  • otherwise, it happens right
• nctrees are now dynamic. add nctree_del() and nctree_add(). you can now create an empty nctree. #2458
• query palette from terminals supporting this functionality #2442
• restore original palette on terminals lacking XTPUSHCOLORS/XTPOPCOLORS #2435
• stop issuing oc on startup and shutdown, preserving custom palettes #2450
• fix static linking #2454
• add some Kitty keyboard protocol elements we were missing #2439, #2452
• properly handle control sequences split across multiple reads #2448
• properly handle newlines in ncplane_puttext() #2446
• don't allow ncchannels_reverse() to enter illegal states #2421
• copy EGCs when calling ncplane_putc(), as they could be invalidated within (fixes OfflineEGCs unit test) #2420
• fix for Linuxbrew build #2428
• install alternate signal stack handler via sigaltstack() on UNIX #2424
• faster ncplane_resize() when only the y dimension is changing #2425

v3.0.0—IN THE "A"

I keep it playa while some choose to play it safe
boi, check the résumé: it's risky business in the 'A'

Notcurses 3.0.0 “In the 'A'” with API/ABI3

• boom! =]
• major additions since 2.0.0
• what they're saying
• gallery
• the new CLI mode
• porting api2 applications to api3
• what's coming in Notcurses IV
• coda: in the "A"

boom! =]

Notcurses 3.0.0 represents over a year of development since Notcurses 2.0.0 "Stankonia".

The overall vision remains unchanged from the very beginning—composition of z-ordered planes, with an API naturally expressed in terms of 888RGB DirectColor and Unicode Extended Grapheme Clusters, amenable to multithreading—but it's grown beyond all my dreams. Notcurses has pushed the terminal ecosystem forward, with patches and influence going into XTerm, Kitty, Alacritty, MLterm, Contour, foot, the Linux console, iTerm2, MSYS2, console-setup, Valgrind, musl, and some I'm forgetting. Notcurses makes use of advanced new kernel functionality like Linux's pidfds, but at the same time runs on various BSDs, macOS, and even Microsoft Windows (natively, not just through WSL). It fully supports the new Windows ConPTY and Microsoft Terminal. It can be used to build fixed-screen TUIs and scrolling CLIs. Aside from its lack of Curses compatibility, it is—as far as I'm aware—the best, most powerful, ballinest terminal graphics library in existence.

If you're writing a new terminal application in 202x, you probably ought be using Notcurses.

help wanted/needed

are you a python hacker with a solid understanding of wrapping C? because i absolutely am not, and honestly have no interest in becoming one. i desperately need someone committed to adapting new C functionality in python as it emerges, ideally further extending that to create a truly pythonesque Notcurses interface. pick up @igo95862 's work in python/ and go to town. do you write go? same shit! c#? dot-net this motherfucker! what's in it for you? i wish i knew the answer to that question myself. @joseluis seems to have the situation pretty well handled for rust; ask him. i'll be handling fortran, prolog, and threaded intercal wrappers.

left: a python eats a crocodile, before unhinging its dynamically-typed jaw and eating my time. note that the python is devouring the crocodile without a hint of parallelism, despite having seemingly evolved for, like, six hundred million years now. i bet it OOMs.

API and ABI break

Notcurses 3.0.0 introduces a hard ABI break relative to previous versions, and changes the SONAME to reflect this. Previous binaries will not link against Notcurses 3.0.0+. Even if you use no new API, nor any API which has been deprecated, your binary must be recompiled. The API has expanded throughout 2.x development, but 3.0.0 removes all functionality previously only deprecated. See the API changenotes below for complete information. I'm sorry for the API changes, but they leave Notcurses much improved for the future. Most changes can be safely implemented via global regex.

There may be any number of additions to the API for Notcurses 4, but every attempt will be made to maintain backwards compatibility. The ABI will not change across 3.x development.

major additions since 2.0.0

With that, the most major changes since 2.0.0 include:

• Direct interrogation of terminals, when present, to determine capabilities—Notcurses is moving away from reliance on Terminfo. Capabilities acquired in this fashion aren't dependent on the local copy of the terminfo database, nor upstream authors getting their terminfo changes into NCURSES, and especially not on the user correctly setting TERM.
• Support for XTMODKEYS and the Kitty keyboard protocol for rich events. Support for console mice via GPM. Note that the Kitty keyboard protocol is now supported by foot! Among other things, this allows disambiguation of key depress, repeat, and release, as well as detection of modifier keys by themselves. Clients can now specify which mouse events they want, and get mouse movement events even when no buttons are pressed.
• Support for Sixel and Kitty bitmap graphics, and direct draws to the Linux framebuffer console. Note that Kitty graphics are now supported by WezTerm! Bitmap capabilities are determined at runtime, and no matter what the backend, they're efficiently integrated into the overall z-axis model. They cover glyphs, and are covered by glyphs, just like any other plane. As always, Notcurses steps down among its blitters based on local capabilities.
• The Unicode 13-based 3x2 "sexblitter" and 8x1 "eightsplotter" were added.
• Support for Microsoft Windows, macOS, and Dragonfly BSD. macOS support benefitted greatly from @michaelsbradleyjr 's assistance testing, setting up GitHub CI, and providing a development platform. Windows support benefitted greatly from the wisdom and grandmotherly patience of @j4james. Both were substantial efforts, with Windows being by far the larger one, consuming close to two months' development time. It was worth it, though, to show off the powerful new Microsoft Terminal and the ConPTY, wherein Microsoft gets it almost right. Notcurses is nothing less than a sea change for Windows console app developers.
• Non-interpolative scaling suitable for e.g. pixel art.
• Scrolling on the standard plane for construction of CLI-like programs in Rendered Mode.
• New nctree, ncprogbar, and nctabbed widgets, the latter from @MasFlam.
• Much-improved Python wrappers from @igo95862.
• Rust wrappers taken to an entirely new level by @joseluis.
• Construction of ncvisuals via various RGB formats, as requested by @kaniini .
• libnotcurses-core has been split out from libnotcurses, allowing binaries to be linked without the multimedia stack, even if the installed Notcurses was built with a multimedia stack.
• Distinct rendering contexts are available as piles; there are no concurrency hazards shared between piles.
• The new notcurses-info binary provides a quick summation and exercise of terminal capabilities.
• The new ncls binary lists and renders files.
• notcurses-view has been renamed to ncplayer, and now accepts -n for non-interpolative scaling, and -a to alpha-mask a color.

...but this is only a small sample of the expansions, improvements, and achievements of Notcurses 3.0.0! Give it a test drive. Write some apps around it. Hack. May one hundred flowers bloom! 百花齊放，百家爭鳴

868 issues were closed via 7.7K+ commits in this release cycle.

what they're saying

The first time I ran notcurses’ “jungle” demo in foot nothing happened. Turned out to be a bug in foot’s handling of color palette changes. This phenomenon has kept repeating itself; notcurses using features in novel ways unearths terminal emulator bugs. notcurses-demo turns your terminal emulator into a 90s computer demo—and that’s a good thing."
—Daniel Eklöf (@dnkl), author of foot

I believe notcurses forms an excellent foundation for the next generation of terminal applications, with rich support for graphics and input, and lots of effort into graceful degradation for legacy terminals. I recommend anyone starting to build a terminal application in 2021 consider it as the foundation layer.
—Kovid Goyal (@kovidgoyal), author of Kitty

Terminals have long been seen as an old era tech, and so, many applications retain the behavior of those apps and standard being even older than I am. Notcurses not so much! I am glad notcurses is trying to break out and breathe fresh air and new life into our beloved eco system again with many features the young generation of users and developers want and will expect. A huge thanks to Nick Black for helping us move forward in the terminal land. The notcurses demos are mind blowing and inspiring of what modern terminal applications can be capable of and I recommend anyone asking me what to use when building terminal apps to give notcurses a try. Hack on!
—Christian Parpart (@christianparpart), author of Contour

The demo is great, and looks like it can push out enough detail to pull off silliness like pushing an SNES game’s output straight to the console. What might be the most impressiv...

v2.4.9—bears that dance

The judge set the bottle on the bar. Hear me, man, he said. There is room on the stage for one beast and one alone. All others are destined for a night that is eternal and without name. One by one they will step down into the darkness before the footlamps. Bears that dance, bears that dont.—Cormac McCarthy, Blood Meridian

---

This is the final release planned for the 2.x.x series. The next release will be 3.0.0, shipping SONAME 3. This will be an API break, as well; all functionality currently marked deprecated will be removed. So long as you are not using deprecated functions, impact ought be minimal, perhaps requiring only a recompile.

---

• ncvgeom now has its rcellx and rcelly fields filled in, providing the rendered dimensions in terms of cells. This is thus immediately available to callers of ncdirectf_geom(). The new function ncvisual_geom() replaces ncvisual_blitter_geom(), which has been deprecated, and fills in an ncvgeom with this and other information.
• notcurses_mice_enable() and notcurses_mice_disable() have been added, replacing notcurses_mouse_enable() and notcurses_mouse_disable(). notcurses_mice_disable() is a static inline wrapper for notcurses_mice_enable(NCMICE_NO_EVENTS). notcurses_mice_enable() accepts a bitmask over types of mouse event. Mouse movement without a button pressed can now be tracked with NCMICE_MOVE_EVENT. For the old behavior (report only when a button is pressed), use notcurses_mice_enable(NCMICE_BUTTON_EVENT).
• On transitions between ncplanes during rendering, on terminals known to have complex handling of glyphs, Notcurses will now sometimes issue hpa ("horizontal position absolute") control sequences that ought not be necessary, but ought normalize position when Notcurses and the terminal disagree about glyph width. The number of sequences thus issued is available as the new stat hpa_gratuitous. This fixes some longstanding bugs in e.g. the [whiteout] and [uniblock] demos.
• Some improvements to ZWJ handling and Unicode segmentation.
• Clean up ncdirect_cursor_yx thanks to new input system.
• Only send XTMODKEYS if the Kitty keyboard protocol is not available.
• Prefer XTVERSION results to the TN value of XTGETTCAP.
• Fix bug when width was 2 in ncdirect_box().
• [mojibake] add the Unicode 7.0 emoji, which were missing for whatever reason.
• Eliminate recursion in ncplane_polyfill_yx() and ncvisual_polyfill_yx(), fixing bug on environments with small stacks.
• Stop issuing LTR forcings following RTL bidi Unicode.
• FIx regression in [fission] demo that drew background over previous material
• Cap size of orca in [intro] demo at 1/4 width, 1/3 height of screen
• Fix small memory leak in nctree
• Wait for input at end of procroller PoC
• Use NCSCALE_STRETCH instead of NCSCALE_NONE in some unit tests so they work on small screens
• Use rgb with XTGETTCAP to detect DirectColor unambiguously on supporting terminals
• Properly flush the clear before completing raster in notcurses_refresh()
• Use u7 for cursor location reports on Microsoft Windows

v2.4.8—remember this day

OK, after a few kinda rough releases--it's been a difficult month--I feel really, really good about this one. I believe 2.4.8 will honor its righteous progression of powers-of-two. Very few new features here, but instead lots of subtle fixes and analysis. Also, full Unicode 14.0 support on macOS now!

• Multithread the [view] and [yield] demos (#1613)
  • improves their performance on most platforms
  • provides examples for multithreaded employment of multiple ncpiles
• Fix bug in notcurses-demo where [zoo] left its background plane up
• Fix bug in Kitty graphics rendering where glyphs under opaque sprixcells weren't invalidated, but needed to be
  • Fixes several longstanding bugs in notcurses-demo (#1932, #2297)
• Fix a bad memory leak in ncvisual_stream() (#2286) and several others on error paths (#2282)
• Fix bad memory write when wiping/rebuilding sixel which is partially offscreen (#2287)
• Fix use-after-free in automaton construction that likely never hit anyone, but was lurking (#2279)
• Address scan-build warnings, some of them real, others (i think/hope) not (#1348)
• Allocate auxiliary vectors appropriate for graphics protocol, saving 50% of memory for fbcon / kitty-static
• Don't discount a character simply because wcwidth() returns -1; gets most Unicode 13 working on macOS (#2285)
• Support environment variable NOTCURSES_LOGLEVEL (#2277)
• [keller] demo now exits out when it fails to blit something it thinks ought have worked (#2278)
  • Fix bitmap sizing bug this surfaced
• Add USE_ASAN to build with AddressSanitizer, add several compiler optimization flags for floating point (but not the rollup -ffast-math, which includes -ffinite-math-only, which is incompatible with libav, which sometimes reports NaN for timing information). Do not enable this unless actively debugging; it will greatly reduce performance!

The man he stepped up to the microphone and he gave it a kiss.
It was a big wet, slippery kiss.
He had sweat dripping off of his nose onto the windscreen.
As he looked out over the audience he said,
"God bless you, God bless you one and all."
Then he took a can of Ronson lighter fluid
and he squirted it over the top of his head,
and proceeded to light himself on fire,
and as he stood there glowing he said,
"Remember this day."

v2.4.7—learn to swim

be aware: 3.0.0 and ABI3 are coming soon! this will see all deprecated material removed, possibly requiring code changes on your part. be sure you're actively moving away from deprecated functions (they're all marked, and ought elicit compiler warnings).

• Add full support for features 2 and 8 of the Kitty keyboard protocol. This results in very thorough coverage of keyboard events, but some of them might be unexpected. Each keypress will typically now result in at least two input events (a press and release). Keys that previously resulted in no event (e.g. shift, alt, etc.) now result in events. These events will only be generated on Kitty or other terminals implementing this protocol.
• XTMODKEYS is now used where supported, providing more coverage of keyboard events.
• Sixel support was previously detected via XTSMGRAPHICS replies. It is now predicated on the presence of a '4' feature in the Device Attributes response. As a result, Sixel is now supported on numerous terminal emulators where it was not previously detected. Terminal authors are strongly encouraged to implement XTSMGRAPHICS if implementing Sixel.
• ncvisualplane_create() now allows for a new pile to be created by passing a NULL ancestor plane in vopts.
• ncvisual_render() has been deprecated, replaced by ncvisual_blit(). ncvisual_render() is still available, but will be removed for ABI3. The new function is pile-aware. When a NULL value is passed as vopts->n, or when vopts itself is NULL, a new plane will still be created, but it will now be in a new pile (previously, the new plane would be in the standard plane). To maintain the old behavior with ncvisual_blit() (i.e. to make a new plane bound to the standard plane), pass the standard plane as vopts->n, and add NCVISUAL_OPTION_CHILDPLANE to n->flags. See #1462.
• Use unnamed pipes on Windows for input readiness notification.
• constify most of the relevant members of various widget creation options.
• notcurses-demo now uses seconds rather than semiseconds as the base unit of the FPS plot.
• Detect GNU screen. Never attempt to use RGB with screen 4.
• Support smooth bitmap movement / precise bitmap placement when using the Kitty graphics protocol. Support will be added for sixel and fbcon soon. Use the new pxoffy and pxoffx members of the ncvisual_options struct.
• Replace all wcstombs() calls with thread-safe wcsrtombs().
• Send synthesized signals even when NCOPTION_INPUT_DRAIN is in use.
• Extract version from Secondary Device Attributes for older XTerms.
• Properly reset the keyboard state after a crash in initialization.
• Properly push and pop keyboard states when switching to and from the alternate screen post-initialization.
• Widget input handling functions ignore all keyboard event types save press.
• Add new NCKEY constants for modifiers and other keys which previously didn't generate events.
• Use explicit CRLFs where necessary on Windows, fixing banners.

v2.4.5—victory's flawless

• If you currently have 2.4.4 installed/packaged, I urge you in the strongest of terms to upgrade to 2.4.5. I conjectured in the 2.4.4 release notes that the massive input automaton unification would probably have some bugs shake out. That conjecture was demonstrated true. Most noticeably, backspace didn't work in most terminals, and Notcurses would sometimes hang during initialization (this was dependent on where on the screen it started). All discovered problems in the input layer have been resolved.
• Support has been added for feature 2 of the Kitty keyboard protocol, along with XTMODKEYS where that extension is supported. The upshot is that we can now properly identify more combinations of special keys and modifiers.
• Support has been added for media keys when using the Kitty protocol.
• Properly initialize evtype for resize events.
• Avoid divide-by-zero in intro demo when we knew cell geometry but not pixel geometry.
• Added "Notes for Terminal Authors" section to TERMINALS.md
• Add some line-editing shortcuts to ncdirect_readline().
• Properly reset the terminal when no output is generated.
• Drop mouse events in the right and bottom margins.
• ncplane_dup now works correctly on root planes.
• Fix a bug in ncdirect_reparent_family() that led to invalid memory accesses.
• Added ncplane_move_family_{above, below}()
• Added ncplane_move_family_{top, bottom}()
• Fix workaround for kitty default background color being treated as transparent
• Remove poorly-thought-out ncplane_boundlist(), which I hope no one was using.
• Distinguish between known and unknown default background color in notcurses-info.

v2.4.4—no scrubs

Qui si convien lasciare ogne sospetto; ogne viltà convien che qui sia morta.
—Dante Alighieri, The Inferno, Canto III, 14-15

I am dankamongmen, wrangler of automata! Look upon my works, ye Mighty, and despair! This release sees the much-heralded unification of input automata, and the most complex bit of coding since at least the initial pixel blitter work, and very possibly the most complex code in the project. Essentially, we have two sources of input escape sequences we need match: simple strings dynamically loaded from terminfo, and regex-like sequences statically hardcoded into the library. Previously, we had two distinct automata: a dataflow-based one for the (acquired at runtime) terminfo sequences, and a controlflow-based one for the (known ahead of time, but more complex) response sequences. Being a man of taste and means, this was completely aesthetically unacceptable. We now build a single, wholly dynamic, dataflow-based automaton encompassing all possible control sequence inputs. Being much too cool/stupid/autistic to simply string together some ɛ-transitions (are we remembering our Sipser, or perhaps our Hopcroft+Ullman, friends?), spool out a GNFA, take the power set, apply Glushkov/Thompson and reduce that fucker (the idea of using some other jabronie's DFA library was of course never considered), we build the reduced DFA on the fly, which is probably way more difficult than you think.

I've tested it in my standard set of testing terminals, and held off from release until it seemed perfect in all. I'm sure you'l find some small (or larger) issues, though, so please file bugs and have a little patience. It's been a long week.

Besides that...

• Notcurses no longer uses libreadline, as it was realized to be incompatible with the new input system. ncdirect_readline() has been rewritten to work without libreadline, which means it's now always available (readline was an optional dependency). NCDIRECT_OPTION_INHIBIT_CBREAK should not be used with ncdirect_readline(), or else it can't implement line-editing keybindings. Packagers, please stop supplying -DUSE_READLINE to CMake, and drop libreadline from Notcurses dependencies.
• ncwcsrtombs() has been added to convert a wchar_t* to a heap-allocated, UTF8-encoded char*.
• For those of you paying by the electron, -DUSE_CPP=off can now avoid any need for a C++ compiler. This cannot be used with -DUSE_MULTIMEDIA=oiio, since OpenImageIO is fundamentally C++. You also won't be able to build the NCPP C++ wrappers, natch, nor notcurses-tester, notcurses-input, ncplayer, nor even humble nctetris.

So. Not the most exciting release for y'all, but very exciting for me. Next time, more cool shit you can use!

v2.4.3—the boss like king koopa

• Use posix_spawn() and its ass-ugly API in place of fork()+exec*() #2194.
• Fix a bug in ncplane_erase_region(), and make it much more general. It can now be used for cursor-relative erasure through the end/beginning of the current line, etc #2181.
• It was recently discovered that many terminals, including XTerm, had inverted the semantics of DECSDM aka "Sixel Display Mode". Since then, a number of these terminals have changed their semantics to match the VT340 semantics. Unfortunately, this means older versions of Notcurses now display all sixels in the upper left of the visual area. Notcurses now knows the semantics changed in XTerm 369, the ayosec/graphics branch of Alacritty 15.1, foot 1.8.2, and MinTTY 3.5.2 #2205. Many thanks to @j4james for his assistance here, and general spearheading of this ecosystem-wide change.

If it weren't for that last, I probably wouldn't have bothered to release just yet. Most work this week was on #2183, which isn't easily visible from the outside, but is absolutely critical for robust and performant handling of input. It's been a fascinating problem -- take a look at #2208 to see what all's going down. automata theory, huzzah! but yeah, not too much here, been busy at the day job, sorry i'll try to suck less ass.

btw if anyone needs multi-gigabit low-latency satellite transit, i can get you a good price!

v2.4.2—as if she were the last one she thought i'd betray

ok look, this one has an absolute shitton of churn in it. i'd not have released it yet, except a few bugfixes needed to go out. here's the deal: i completely rewrote the input subsystem, which was already complex as hell. it now spawns its own thread so that i can reliably get terminal messages even if you're not looking for input--i have to have my own execution context involved. it is a great improvement overall, but has deep, subtle, platform-specific effects.

Microsoft Windows definitely regresses a bit with this release; I recommend you stick to 2.4.1 on that platform. otherwise, brave souls are encouraged to beat on this, and report any bugs you find.

• The Rust bindings are no longer included in the main Notcurses repository. They can instead be found here: dankamongmen/libnotcurses-sys
• Notcurses now supports Unicode 14 (if the underlying system supports it).
• The input subsystem has been completely rewritten, making it much more robust.
  • NCOPTION_DRAIN_INPUT and NCDIRECT_OPTION_DRAIN_INPUT have been added. Your program ought use them if it doesn't intend to handle input. Failure to do so will result in unnecessary work, and possibly even dropped messages from the console.
  • A distinct input thread is now spawned, ensuring responsive handling of terminal control sequences even when the user isn't actively looking for input.
  • Notcurses can now distinguish between a key press, a repeat, and a key release for some events. NCKEY_RELEASE has been removed. When a mouse button is released, you'll now get the actual button (plus NCTYPE_RELEASE).
  • When input is redirected from a file, notcurses-input will now exit once the entire file is processed. Not coincidentally, NCKEY_EOF now indicates the end of input.
  • notcurses_getvec() allows batched reads from input.
  • Sequences beginning with an Escape character that aren't recognized control sequences are now returned as input.
  • GPM mouse events now account for margins.
  • Mouse clicks in the margins are no longer returned.
• SIGWINCH and SIGCONT are now masked in the thread that calls notcurses_init(). This is because the addition of a distinct input thread exacerbated the problem of SIGWINCH being delivered to an unexpected thread. While this change will suffice for otherwise single-threaded programs, it remains your responsibility to ensure all threads have masked SIGWINCH and SIGCONT. See the FAQs!
• A bug was fixed when moving graphics using the Kitty protocol in the presence of margins.
• A bug was fixed when using multiframe bitmap graphics using the Kitty protocol, and a graphic was drawn over, then restored.
• A resize callback can now be set for the standard plane.
• A bug was fixed when characters were erased in a resize callback, thanks @kevinconley19.
• Notcurses now supports libavformat 59+.
• Cell blitting in direct mode is now faster and more robust.
• ncneofetch no longer attempts to run xrandr on Microsoft Windows.
• ncneofetch properly centers its logo now, a problem most noticeable on macOS.

v2.4.1—gather all my forces all together rally round

• Fixed up nasty memory leak with NCBLIT_PIXEL. Turns out valgrind doesn't track mmap() by default, a fact of which I was sadly unaware (#2150).
• Support for second generation kitty animation was determined to break down in the presence of multiframe plus wiping/rebuilding. This was fixed, but it led to unacceptable slowdown. I've instead disabled second generation animation support until this is fixed (#2143, #2161).
• Properly synthesize SIGINT and SIGQUIT from kitty keyboard protocol.
• Properly send the kitty keyboard pop directive to the alternate screen when it's being used. Fixes the terminal being left in an unexpected keyboard state on exit on kitty when redirected (#2149).
• ncneofetch now properly extracts the macOS version (#2158).
• Some small fixes and tweaks to plots. The summary number now describes the ongoing slot, so it spins up in e.g. notcurses-demo (#2152).
• Added ncstrwidth_valid() (#2153).

2.4.2 work will hopefully see the new input subsystem completed, plus resolution of some CLI-mode problems seen on macOS.

hack on!