Aski v0.8.0

Aski v0.8.0

v0.8.0 is the second release on this repository's public history. It corrects how raster
output interprets cell colors, validates GIF loop counts, adds aski render options for the
algorithm, dither strength and palette, and adds a CLI packaging script and a Swift Package
Index documentation config. The full list is in the changelog.

Highlights

• New aski render options (ASKI-82). --algorithm logPolar|dotMatrix, --coverage 0...1
  and --palette fullColor|monochrome. The defaults (logPolar, 0, fullColor) produce the
  same output as before. --write-manifest records the three values as optional fields in the
  existing v1 render manifest schema.
• Character-art recipes. The recipes guide gives three
  CLI recipes with their exact commands and the PNGs they produce from the bundled Carina image.
  Each uses at least one of the new options above.
• Glyph cycling with dotMatrix (ASKI-81). Animation glyph cycling now changes glyphs under
  dotMatrix; candidates after the base pick are the glyphs nearest in ink density. The base frame
  is unchanged.
• CLI text output to /dev/null and /dev/stdout (ASKI-83). aski render --output can
  discard text or send it to a pipe while --render-png writes the image.
• Updated logPolar guidance (ASKI-79). The documentation now recommends logPolar only with
  the standard and braille character sets, and points to dotMatrix for the sets it renders
  blank or with a few repeated glyphs. Converter output did not change.
• README hero (ASKI-15). The README image is now a default-settings render from the current
  build, with the command that produces it.

Behavior and source changes

• Raster colors change (ASKI-3). ASCII, tile and effects rendering previously interpreted
  encoded sRGB and Display P3 cell colors as Generic RGB. They now use the grid's declared color
  space, and AskiRenderEngine converts colors when its output gamut differs from the grid's.
  Raster colors change, including mid-gray neutrals. Glyph selection and attributed-string colors
  do not change. Review saved renders and remove any compensation for the old colors.
• CLI colors are sRGB. --background, --mask-fallback-color and --mask-ground are built
  in sRGB. aski render --background "#808080" now writes #808080 pixels; it wrote #929292
  before. The value now matches the #RRGGBBAA value recorded in the manifest.
• GIF loop counts are validated (ASKI-8). ASCIIGIFEncoder.write accepts loopCount in
  0...32767 (0 is infinite, 1 plays once) and throws the new
  GIFEncodeError.invalidLoopCount(_:) for other values before it creates the file. This new
  enum case is a source break for exhaustive switch statements over GIFEncodeError.
  GIFEncodeReport.loopCount now reports the value read back from the written file.
• Other special CLI destinations are rejected. Apart from /dev/null and /dev/stdout,
  special files such as FIFOs are rejected as --output before any output changes. PNG and
  manifest destinations must be regular files.

No other public declarations in the Aski module were added, removed or changed since v0.7.0.

Upgrading

Pin the release exactly:

.package(url: "https://github.com/BigCactusLabs/Aski.git", exact: "0.8.0"),

Aski is pre-1.0; an exact pin keeps upgrades deliberate. Then:

1. Add a branch for GIFEncodeError.invalidLoopCount to any exhaustive switch over
   GIFEncodeError, and handle source GIFs whose loop count is outside 0...32767.
2. Re-render and review saved raster output, and remove any manual color compensation for the
   previous Generic RGB interpretation. Build background, mask-fallback and ground colors with
   explicitly tagged CGColor values such as CGColor(srgbRed:green:blue:alpha:).
3. Regenerate CLI renders made with --background, --mask-fallback-color or --mask-ground
   before comparing them with new output.

The migration notes cover these steps with
links to the rendering, video and command-line guides.

For contributors

• CLI candidates. just package-cli <new-dir> builds an arm64-only, relocatable aski
  candidate, checks its resources, smoke-tests a relocated copy and writes an archive with
  SHA256SUMS. It does not run the acceptance gates or publish anything. See the
  distribution guide.
• Swift Package Index. .spi.yml declares Aski as the documentation target.
• DocC Markdown export path. ./Scripts/validate-docc.sh --emit-markdown no longer writes to
  /tmp/aski-docc-markdown, which the v0.7.0 notes describe. It prints the directory it created;
  pass --output-dir <new-dir> for a fixed location.
• Script tests. just test-infra runs portable regression tests for the doctor, DocC and
  Metal-restoration scripts with Python 3. It does not replace just check.
• Render goldens. Goldens changed by ASKI-3 were re-recorded on macOS 27.0.1 / Xcode 27.0 /
  Swift 6.4. Exact raster output also depends on the host machine; see the
  toolchain and snapshot baseline.

Licensing

Licensing is unchanged from v0.7.0: Apache License 2.0 (see LICENSE and
NOTICE), with bundled Courier Prime under the SIL Open Font License 1.1.

Verification

Release PR #20 records the just check, just release-preflight, and DocC
Markdown export results together with the commit they ran on.

Assets

No prebuilt CLI binary is attached to this release. Build the CLI from a checkout as the
command-line guide describes. Check the
published release for any documentation assets actually attached.

Aski v0.7.0

Aski v0.7.0

Pictures, reconsidered as type. Now with a public front door.

v0.7.0 is the first release on this repository's public history. The history begins at a single
root commit that holds the code and the published research; development before it happened in a
private repository. The v0.6.0 tag and earlier tags do not exist here. Issue, pull-request and
commit references in the changelog and under docs/ from before this release point to that
private history.

Highlights

• A clearer way in. The README now starts with a bundled-image demo and
  Swift integration. A dedicated command-line guide,
  contributor guide, refreshed DocC onboarding, and expanded llms.txt
  separate everyday use, development, and research. Current defaults, platform requirements,
  plain-text/color behavior, and experimental boundaries are explicit.
• Unified aski lab command tree (ASKI-48). aski lab {color,motion,video,accessibility,decolor,hdr,preset}
  replaces the separate lab executables, with Bash, Zsh and Fish completions for the full tree. The
  historical Aski*Lab products remain as thin shims with identical help, usage and exit codes.
• Masks and photo dissolve in the CLI (ASKI-43, ASKI-44). aski render --mask accepts raster
  masks with transparent, solid-color or original-photo fallbacks, sizing modes, hard edges and
  inversion. The new MaskOptions.groundColor places a color behind active glyphs and tiles.
• Exact target-width PNGs (ASKI-63). ASCIIGrid.renderImage(font:backgroundColor:targetPixelWidth:preserveSourceAspect:)
  and aski render --width render to an exact pixel width, supersampled 4x and averaged down in
  linear light. PNG size no longer depends on --font-size.
• Bottom and right edges are sampled again (ASKI-65). Converters used to skip the last
  height % rows rows and width % columns columns of the source, up to 10% of the image height,
  and the result looked stretched downward. The full image is now sampled; every rendered-grid
  golden was re-recorded with no tolerance loosened.
• Transparent PNG backgrounds. aski render --background clear (or transparent) produces an alpha-zero
  ground for --render-png. The opaque-black default is unchanged.

Breaking changes

• ASCIIAlgorithm.edgeMap is removed (ASKI-16). It picked the wrong stroke orientation in 9 of
  20 test cases even after two fixes. Use .logPolar (the default) or .dotMatrix. Removing
  edgeMap did not change those algorithms; the separate sampling fix above can change output.
• RenderingOptions has five public controls instead of twelve (ASKI-68). Occupancy matching,
  shape-structure assist, steerable-shape assist, ink pre-compensation and chroma-shape assist were
  default-off experiments that failed or stayed inconclusive; they are gone from the public API.
• Custom character sets are snapshotted (ASKI-71). ASCIIConverter copies a character set's
  glyph arrays when it is initialized or when characterSet is assigned. A reference-type set that
  mutates its arrays in place must be assigned again before the next conversion.
• swift-argument-parser minimum 1.8.0 (ASKI-47). The requirement is now from: "1.8.0".

Migration

After the tag is published, consumers moving from private-history pins can adopt the public
repository with an exact version:

.package(url: "https://github.com/BigCactusLabs/Aski.git", exact: "0.7.0"),

Before publication, use a source checkout or a local package dependency. Aski is pre-1.0;
exact pins make upgrades deliberate rather than promising source or output stability.

Code using .edgeMap or removed RenderingOptions controls needs the changes above. Custom
character-set owners should review snapshot semantics. For earlier API changes and before/after
examples, see Migration Notes.

Licensing

Aski is licensed under the Apache License 2.0; see LICENSE and
NOTICE. Bundled Courier Prime remains under the SIL Open Font License 1.1. The
committed ShapeData glyph descriptors are measured from the system Courier font, as recorded in
NOTICE. Corpus assets retain their own attribution and terms.

For contributors

• Render goldens and default.metallib are recorded on macOS 27 / Xcode 27 (ASKI-77); the render
  snapshot suites fail on macOS 26. Glyph selection output is unchanged by that baseline refresh.
• just doctor and just release-preflight no longer require a specific Xcode; the Swift minimum
  comes from swift-tools-version.
• The contributor guide distinguishes library deployment minimums from
  snapshot requirements and explains the local gates. This repository has no hosted CI workflow.

Verification

The release-preparation checks recorded in PR #3 were run at f18869e on
macOS 27.0 / Xcode 27.0 / Swift 6.4, before the public-documentation audit. They do not
verify later commits. Before tagging the final release commit, rerun:

just check
just release-preflight
./Scripts/validate-docc.sh --emit-markdown

Record the final commit and results in the release PR. Regenerate the DocC assets from that
checkout so they include the new command-line guide and updated articles; do not reuse the
pre-audit sidecars. The documentation audit does not substitute for these macOS gates.

Assets

The release's intended documentation assets are:

• Aski-markdown-manifest.json: DocC Markdown manifest indexing public API symbols with anchors and cross-references.
• aski-docc-markdown.tar.gz: tarball of the per-symbol Markdown sidecars.

--emit-markdown writes its output under /tmp/aski-docc-markdown; packaging and uploading
release assets are separate steps. Check the published release for the files actually attached.