inklet 3.1.0__tar.gz → 4.0.0.dev1__tar.gz

{inklet-3.1.0 → inklet-4.0.0.dev1}/.github/workflows/checks.yml

@@ -58,7 +58,28 @@ jobs:
       - name: Build the preset comparison gallery
         run: .venv/bin/python tools/preset_gallery.py --output out/presets
       - name: Common CSV plotting example
-        run: .venv/bin/python examples/general_plots.py --output out/general-plots
+        run: |
+          .venv/bin/python examples/general_plots.py --output out/general-plots
+          .venv/bin/python examples/plot_quality_review.py --output out/plot-quality
+      - name: Experimental selection and revision baseline
+        run: |
+          .venv/bin/python examples/v4/linked_selection.py --output out/v4-linked
+          .venv/bin/python examples/v4/browser_scatter.py --count 3000 --output out/v4-browser
+          .venv/bin/python examples/v4/linked_dashboard.py --output out/v4-dashboard
+          .venv/bin/python examples/v4/faceted_operations.py --output out/v4-facets
+          .venv/bin/python examples/v4/time_series.py --output out/v4-time
+          .venv/bin/python examples/v4/statistical_views.py --output out/v4-statistics
+          .venv/bin/python examples/v4/regional_report.py --render --output out/v4-regional-report
+          .venv/bin/python examples/v4/engineering_report.py --render --output out/v4-engineering
+          .venv/bin/python examples/v4/scientific_report.py --render --output out/v4-scientific
+          .venv/bin/python examples/v4/mesh_fields.py --render --output out/v4-mesh-fields
+          .venv/bin/python examples/v4/contours_streamlines.py --render --output out/v4-contours-streamlines
+          .venv/bin/python examples/v4/regional_analysis.py --output out/v4-regions
+          .venv/bin/python examples/v4/region_shapes.py --output out/v4-region-shapes
+          .venv/bin/python examples/v4/world_population.py --output out/v4-world
+          .venv/bin/python examples/v4/world_population.py --year 2019 --output out/v4-revision
+          .venv/bin/python examples/v4/world_population.py --switchable --output out/v4-switchable
+          .venv/bin/python tools/benchmark_v4.py --repeat 1 --label ci --output out/v4-baseline.json
       - name: Build the mathematical showcase library
         run: .venv/bin/python tools/showcase_gallery.py --plots-only --quality preview
       - name: Coordinated biology figure and data export
@@ -90,6 +111,42 @@ jobs:
           retention-days: 7
           if-no-files-found: ignore
 
+  tables:
+    name: Table adapters (${{ matrix.dependencies }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        dependencies: [minimum, current]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: '3.12'
+      - name: Install current locked adapters
+        if: matrix.dependencies == 'current'
+        run: |
+          uv venv
+          uv pip install -r requirements-tables.txt -e .
+      - name: Install minimum supported adapters
+        if: matrix.dependencies == 'minimum'
+        run: |
+          uv venv
+          uv pip install -e '.[dev]' 'pandas==2.2.0' 'polars==1.0.0' 'numpy==1.26.4'
+      - name: Table contracts and cross-library figure reconstruction
+        run: |
+          .venv/bin/python -m pytest -q tests/test_table_adapters.py tests/test_temporal_adapters.py tests/test_v4_selection.py
+          .venv/bin/python examples/v4/table_inputs.py --backend pandas --output out/pandas
+          .venv/bin/python examples/v4/table_inputs.py --backend polars --state out/pandas/view.json --output out/polars
+          cmp out/pandas/figure.svg out/polars/figure.svg
+          .venv/bin/python examples/v4/table_inputs.py --backend pandas --revised --output out/pandas-revised
+          .venv/bin/python examples/v4/table_inputs.py --backend polars --revised --state out/pandas-revised/view.json --output out/polars-revised
+          cmp out/pandas-revised/figure.svg out/polars-revised/figure.svg
+          .venv/bin/python examples/v4/time_series.py --backend pandas --output out/time-pandas
+          .venv/bin/python examples/v4/time_series.py --backend polars --state out/time-pandas/view.json --output out/time-polars
+          cmp out/time-pandas/figure.svg out/time-polars/figure.svg
+
   wheel:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 10

{inklet-3.1.0 → inklet-4.0.0.dev1}/.github/workflows/publish.yml

@@ -6,7 +6,7 @@ on:
       tag:
         description: Published GitHub release tag
         required: true
-        default: v3.1.0
+        default: v4.0.0.dev1
         type: string
       dry_run:
         description: Validate release files without uploading to PyPI
@@ -42,11 +42,20 @@ jobs:
           GH_REPO: ${{ github.repository }}
           RELEASE_TAG: ${{ inputs.tag }}
         run: |
-          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
-            echo 'Expected a stable release tag such as v3.1.0' >&2
+          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(\.dev[0-9]+)?$ ]] || {
+            echo 'Expected a stable or development tag such as v3.1.0 or v4.0.0.dev1' >&2
             exit 1
           }
-          gh release view "$RELEASE_TAG" --json isDraft --jq '.isDraft' | grep -qx false
+          gh release view "$RELEASE_TAG" --json isDraft,isPrerelease > "$RUNNER_TEMP/release.json"
+          python - <<'PYCODE'
+          import json, os
+          from pathlib import Path
+          release = json.loads((Path(os.environ['RUNNER_TEMP']) / 'release.json').read_text())
+          if release['isDraft']:
+              raise SystemExit('Publish the GitHub release before uploading its assets')
+          if release['isPrerelease'] != ('.dev' in os.environ['RELEASE_TAG']):
+              raise SystemExit('Development tags must be GitHub prereleases; stable tags must not')
+          PYCODE
           version="${RELEASE_TAG#v}"
           gh release download "$RELEASE_TAG" --dir dist \
             --pattern "inklet-${version}-py3-none-any.whl" \
@@ -59,6 +68,9 @@ jobs:
           python - <<'PY'
           import hashlib
           import os
+          import tarfile
+          import zipfile
+          from email.parser import BytesParser
           from pathlib import Path
 
           dist = Path('dist')
@@ -74,6 +86,20 @@ jobs:
               if hashlib.sha256((dist / name).read_bytes()).hexdigest() != digest:
                   raise SystemExit(f'Checksum mismatch: {name}')
               print(f'Verified {name}')
+          wheel = dist / f'inklet-{version}-py3-none-any.whl'
+          with zipfile.ZipFile(wheel) as archive:
+              metadata_files = [n for n in archive.namelist() if n.endswith('.dist-info/METADATA')]
+              if len(metadata_files) != 1:
+                  raise SystemExit('Expected exactly one wheel metadata file')
+              wheel_metadata = BytesParser().parsebytes(archive.read(metadata_files[0]))
+          with tarfile.open(dist / f'inklet-{version}.tar.gz') as archive:
+              metadata = archive.extractfile(f'inklet-{version}/PKG-INFO')
+              if metadata is None:
+                  raise SystemExit('Missing source archive metadata')
+              source_metadata = BytesParser().parsebytes(metadata.read())
+          for metadata in (wheel_metadata, source_metadata):
+              if metadata['Name'] != 'inklet' or metadata['Version'] != version:
+                  raise SystemExit('Distribution metadata does not match the requested release')
           (dist / 'SHA256SUMS').unlink()
           PY
           uvx --from twine==7.0.0 twine check --strict dist/*

{inklet-3.1.0 → inklet-4.0.0.dev1}/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## 4.0.0.dev1 — 2026-09-08
+
+First installable 4.0 development preview. This collects the linked-document,
+data, map, engineering and scientific work since 3.1.0. APIs under
+`inklet.experimental` and saved-state schemas may change between previews.
+3.1.0 remains the stable release; the full 4.0 roadmap is not complete.
+
+Install explicitly with `python -m pip install "inklet==4.0.0.dev1"`.
+See the [preview guide](docs/development-preview.md) for examples and boundaries.
+
+- Add immutable rectilinear nodal fields with explicit triangle interpolation,
+  linear contours, normalized-vector RK4 streamlines and cell-linked selections.
+  Preserve scalar/vector masks independently and report tracing termination.
+- Add a complete contour/streamline report with analytic fixtures, source
+  revisions, JSON replacement, saved states and two-width vector exports.
+  Keep corner summaries distinct from interpolated field values.
+
+- Add immutable triangle meshes with supplied scalar/vector face fields, units,
+  source digests, geometric measurements and strict table correspondence.
+  Link equal-scale plan views, triangle picking and calibrated vector arrows
+  to plots, with fixed bins and explicit missing/zero-vector behavior.
+- Add a mesh-field report with a native vector 3D reference, geometry/value/removal
+  revisions, JSON replacement, saved states and exports at two physical widths.
+  Preserve scalar colors by disabling lighting modulation in the 3D data view.
+
+- Add calibrated label-image measurements with explicit region correspondence,
+  missing-intensity semantics, immutable source snapshots and source digests.
+  Link lossless reference images to pixel-accurate region selection and plots,
+  including holes, disconnected regions and non-square pixel calibration.
+- Add a scientific report with calibration, intensity and label revisions,
+  saved-state reconstruction, JSON replacement, visible measurement methods and
+  two-width exports. Improve canvas resolution for embedded vector labels.
+  Preserve vector boundaries and labels over raster imagery;
+  bound browser pixel/outline work without implicit approximation.
+
+- Link native Inklet drawings to experimental browser tables with measured
+  panel layouts, outlined vector assets, stable paint IDs, rectangular picking
+  targets and per-item selection behavior across SVG/canvas/hybrid display.
+- Add immutable axis-aligned box assemblies with explicit units, dimensions and
+  zero-thickness sections. Add a linked engineering report with geometry
+  revisions, preserved label offsets, supplied response curves, removed-ID
+  reconciliation and reproducible exports at two physical widths.
+
+- Add experimental entity-linked wide-table series with explicit numeric/date/UTC
+  samples, missing-data gaps, sample-aware picking and facets. Add a complete
+  real-map regional report with simulated monthly values, distributions, group
+  comparisons, CSV replacement, saved-state reconstruction and two-width exports.
+- Add optional Chrome/Chromium SVG-to-PDF conversion for browser scenes, with
+  physical page sizing and vector-content checks. Document this separately from
+  the native Diagram PDF backend.
+
+- Add experimental linked empirical distributions and supplied interval views,
+  including facets, explicit methods/populations, fixed reference curves during
+  filtering and reproducible revised exports. Keep reference curves unpickable
+  and honor per-mark colors across all browser backends.
+- Fix timestamp hover formatting and expose ECDF fractions in tooltips and the
+  accessible table without changing source columns.
+- Improve shared numeric ticks: preserve scientific-label precision, very small
+  values and narrow representable ranges; reject duplicate or out-of-domain
+  positions. Add a four-panel before/after plotting-quality review.
+
+- Add experimental calendar-date and UTC axes to linked plots, with measured
+  calendar/millisecond ticks, explicit offset and precision rules, temporal bar
+  widths and optional elapsed-time line gaps. Add opt-in temporal DataFrame
+  columns, exact millisecond geometry and a simulated daily-batch revision
+  workflow with browser/Python export parity checks.
+
+- Add optional experimental pandas and Polars adapters for keyed tables, with
+  explicit string IDs, column selection, immutable scalar snapshots and missing
+  value normalization. Reject unsupported cells with column/row diagnostics.
+  Add an illustrated workshop revision example with equivalent exports from
+  both libraries and optional-dependency compatibility checks.
+
+- Add experimental linked category panels for lines, bars and scatter, with
+  explicit category order, empty panels, shared scales, within-category line
+  adjacency and visible diagnostics for unassigned rows. Add a six-panel
+  operations example with saved-state and data-revision workflows.
+- Add opt-in shared plot margins to documents and nested grids. Faceted browser
+  figures use them to preserve equal physical data scales despite differences
+  in panel letters and labels; ordinary document layouts retain their defaults.
+
+- Switch between named, Python-compiled data revisions in an offline browser
+  document, with atomic preparation, explicit removed-ID policies, per-revision
+  source credits and downloadable change reports. Dispose replaced renderers,
+  guard in-flight operations and preserve strict saved-state validation. Add a
+  real-map revision demo and browser/Python parity checks, including Unicode IDs.
+
+- Add explicit experimental figure data replacement with preserved row identity,
+  selected/filtered ID reconciliation, viewport policy and a revision report.
+  Rebuild geometry and exports without mutating the old figure. Extend the real
+  world map with a source-year cohort and user-supplied CSV replacement workflow.
+
+- Make a real Natural Earth country/population map the main geographic example,
+  with linked world/Europe views, pinned public-domain inputs and source years.
+  Add country/continent search, explicit HTML attribution and exact integer
+  table display; retain the invented region shapes as regression fixtures.
+
+- Add experimental GeoJSON polygon/multipolygon joins and linked region maps,
+  including holes, shared row identities, fixed color bins, missing values and
+  clipped picking across SVG/canvas/hybrid modes. Preserve physical map aspect
+  and reserve its measured layout area. Add regional analysis and geometry
+  review examples, native browser fill checks and vector/raster export agreement.
+
+- Extend the experimental browser runtime to linked lines, scatter and signed
+  vertical/horizontal bars. Preserve missing/filter gaps, support reversed axes
+  and nonzero baselines, and share clipped geometry with static SVG exports.
+  Add a four-panel monthly operations example, directly restored HTML state,
+  deterministic picking ties and a fix for pointer focus scrolling tall plots.
+
+- Add an experimental offline scatter renderer with SVG, Canvas 2D and hybrid
+  modes, clipped point picking, linked selection, filtering, page pan/zoom and
+  saved-view reconstruction in Python. Preserve measured axes and outlined
+  text, namespace live SVG IDs, and test browser geometry at pixel ratios 1/2.
+  Publish the runnable example and a bounded backend timing/fidelity study.
+
+- Start 4.0 phase A with experimental keyed tables and versioned selection
+  state, explicit rebasing for changed data, three attributed reference
+  fixtures and a finite offline linked-plot example with reproducible exports.
+- Snapshot nested dataset array cells so external mutation cannot silently
+  change values without invalidating compiled figures.
+- Allow all-baseline bar series to retain axes and legends without drawing
+  rectangles or aborting compilation.
+- Add dependency/fitting/metadata compiler timings and fresh-process edit,
+  resize and export benchmarks with explicit local regression ceilings.
+- Keep documentation navigation against the left viewport edge on wide
+  displays; remove the centered shell's 380 px outer gap at 2560 px width.
+
+- Document the proposed 4.0 product and engine roadmap, delivery phases and
+  acceptance criteria. Reserve animation and presentation authoring for 5.0.
+
 ## 3.1.0 — 2026-09-07
 
 Improved plotting, rendering speed, diagram layout and illustrated documentation.

{inklet-3.1.0 → inklet-4.0.0.dev1}/CONTRIBUTING.md

@@ -4,6 +4,11 @@ Use a focused change with a runnable example or minimal reproducer. Describe
 the resulting behavior and how it was checked. Keep numerical inputs and
 expected results explicit; use simulated data when source data cannot be shared.
 
+The [4.0 roadmap](docs/roadmap.md) connects planned user workflows to delivery
+phases and acceptance criteria. Read the [proposed engine plan](docs/design/v4.md)
+when developing new rendering, interaction or authoring capabilities. These are
+planning documents; current contracts continue to apply until changed explicitly.
+
 ## Development environment
 
 From a checkout with Python 3.12 and `uv` installed:

{inklet-3.1.0 → inklet-4.0.0.dev1}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.5
 Name: inklet
-Version: 3.1.0
+Version: 4.0.0.dev1
 Summary: Scientific figures with live data, measured layout, and consistent vector exports.
 Project-URL: Repository, https://github.com/Mapika/inklet
-Project-URL: Documentation, https://inklet.readthedocs.io/en/stable/
+Project-URL: Documentation, https://inklet.readthedocs.io/en/latest/
 Project-URL: Issues, https://github.com/Mapika/inklet/issues
 Author: Mark Marosi
 License-Expression: MIT
 License-File: LICENSE
 License-File: THIRD_PARTY_NOTICES.md
 Keywords: diagrams,pdf,plotting,scientific-visualization,svg
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
@@ -30,6 +30,10 @@ Requires-Dist: pygments<3,>=2.18; extra == 'docs'
 Provides-Extra: images
 Requires-Dist: numpy>=1.24; extra == 'images'
 Requires-Dist: pillow>=10.0; extra == 'images'
+Provides-Extra: pandas
+Requires-Dist: pandas<4,>=2.2; extra == 'pandas'
+Provides-Extra: polars
+Requires-Dist: polars<2,>=1; extra == 'polars'
 Provides-Extra: render
 Requires-Dist: pillow>=10.0; extra == 'render'
 Requires-Dist: resvg-py<0.4,>=0.3.3; extra == 'render'
@@ -75,6 +79,26 @@ then cover axes, dense data, page layout and exports. Figure planning and micros
 ship under `inklet.experimental` as a [research preview](https://inklet.readthedocs.io/en/stable/research-preview/):
 their signatures and report schemas may change.
 
+## 4.0 development preview
+
+**4.0.0.dev1** adds offline linked charts, maps, calibrated images, mesh fields,
+contours and streamlines, with saved selections and reproducible exports.
+It also includes date/UTC axes, facets, pandas/Polars adapters and shared
+plotting-quality improvements.
+
+```sh
+python -m pip install "inklet==4.0.0.dev1"
+```
+
+[Preview guide and examples](https://inklet.readthedocs.io/en/latest/development-preview/) ·
+[4.0 roadmap](https://inklet.readthedocs.io/en/latest/roadmap/) ·
+[Release notes](https://github.com/Mapika/inklet/releases/tag/v4.0.0.dev1)
+
+This is an opt-in development release. Experimental APIs and saved-state schemas
+may change; 3.1.0 remains the stable release. General browser editing,
+depth-aware 3D selection and the remaining 4.0 release gates are still open.
+Animation and presentation authoring remain in the 5.0 direction.
+
 ## Install
 
 Python **3.11 or later** is required. Install from [PyPI](https://pypi.org/project/inklet/):

{inklet-3.1.0 → inklet-4.0.0.dev1}/README.md

@@ -29,6 +29,26 @@ then cover axes, dense data, page layout and exports. Figure planning and micros
 ship under `inklet.experimental` as a [research preview](https://inklet.readthedocs.io/en/stable/research-preview/):
 their signatures and report schemas may change.
 
+## 4.0 development preview
+
+**4.0.0.dev1** adds offline linked charts, maps, calibrated images, mesh fields,
+contours and streamlines, with saved selections and reproducible exports.
+It also includes date/UTC axes, facets, pandas/Polars adapters and shared
+plotting-quality improvements.
+
+```sh
+python -m pip install "inklet==4.0.0.dev1"
+```
+
+[Preview guide and examples](https://inklet.readthedocs.io/en/latest/development-preview/) ·
+[4.0 roadmap](https://inklet.readthedocs.io/en/latest/roadmap/) ·
+[Release notes](https://github.com/Mapika/inklet/releases/tag/v4.0.0.dev1)
+
+This is an opt-in development release. Experimental APIs and saved-state schemas
+may change; 3.1.0 remains the stable release. General browser editing,
+depth-aware 3D selection and the remaining 4.0 release gates are still open.
+Animation and presentation authoring remain in the 5.0 direction.
+
 ## Install
 
 Python **3.11 or later** is required. Install from [PyPI](https://pypi.org/project/inklet/):

{inklet-3.1.0 → inklet-4.0.0.dev1}/THIRD_PARTY_NOTICES.md

@@ -130,3 +130,16 @@ Accessed 7 September 2026. No endorsement by the Allen Institute is implied.
 and recipe are MIT, Mark Marosi. They add native, sampled-section and region
 intensity tables, population spread and CSV exports using the generated
 components above; no additional segmentation validation is implied.
+
+## Natural Earth country maps
+
+`examples/v4/data/world-countries.geojson` and `world-population.csv` are derived
+from Natural Earth's Admin 0 countries at 1:110m. Made with Natural Earth. The
+map data are [public domain](https://www.naturalearthdata.com/about/terms-of-use/).
+The [source manifest](examples/v4/data/world-map-source.json) pins repository
+commit `9380cca83db5f9aef52d5e762765100745f84b27`, the input checksum and all
+transformations. Antarctica is excluded; retained geometry is not simplified
+further. Population estimates and their individual years come from the source
+snapshot and are not current estimates. The original example code is MIT.
+
+Source and terms checked on 2026-09-08.

{inklet-3.1.0 → inklet-4.0.0.dev1}/docs/api.md

@@ -191,7 +191,7 @@ List built-in presets, optionally restricted to one family.
 
 List built-in physical formats accepted by preset().
 
-#### `subfigure(*, width=180, height=None, columns=1, margin=0, gap=6, row_gap=None)`
+#### `subfigure(*, width=180, height=None, columns=1, margin=0, gap=6, row_gap=None, share_plot_margins=False)`
 
 Create a nested grid. Children inherit the enclosing document theme.
 
@@ -229,7 +229,7 @@ A label-sized module. Port coordinates are fractions of its box.
 
 Create a measured module with fractional ports.
 
-#### `class Document(width: 'float' = 180, height: 'float | None' = None, columns: 'object' = 1, margin: 'float' = 4, gap: 'float' = 6, row_gap: 'float | None' = None, theme: 'object' = 'nature', publication: 'object' = None, preset: 'object' = None, _preset_overrides: 'dict' = <factory>, _cells: 'list' = <factory>, _links: 'list' = <factory>, _letters: 'dict' = <factory>, _cache: 'dict' = <factory>, _last: 'object' = None) -> None`
+#### `class Document(width: 'float' = 180, height: 'float | None' = None, columns: 'object' = 1, margin: 'float' = 4, gap: 'float' = 6, row_gap: 'float | None' = None, theme: 'object' = 'nature', publication: 'object' = None, preset: 'object' = None, share_plot_margins: 'bool' = False, _preset_overrides: 'dict' = <factory>, _cells: 'list' = <factory>, _links: 'list' = <factory>, _letters: 'dict' = <factory>, _cache: 'dict' = <factory>, _last: 'object' = None) -> None`
 
 A physical page containing named, live figure definitions.
 
@@ -262,9 +262,9 @@ A resolved snapshot; later authoring changes cannot alter its exports.
 
 A document cannot satisfy its declared physical layout constraints.
 
-#### `document(*, width=180, height=None, columns=1, margin=4, gap=6, row_gap=None, theme='nature', publication=None)`
+#### `document(*, width=180, height=None, columns=1, margin=4, gap=6, row_gap=None, theme='nature', publication=None, share_plot_margins=False)`
 
-Create a live scientific document with a constrained physical page layout.
+Create a live document; optionally share plot furniture across the grid.
 
 #### `class PlotSpec(width: 'float' = 40, height: 'float' = 30, options: 'dict' = <factory>, _steps: 'list' = <factory>) -> None`