inklet 3.1.0__tar.gz → 4.0.0.dev2__tar.gz

{inklet-3.1.0 → inklet-4.0.0.dev2}/.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
@@ -71,6 +92,9 @@ jobs:
         run: |
           .venv/bin/python tools/benchmark_engine.py --repeat 1 --output out/engine-benchmark.json
           .venv/bin/python examples/engine_review.py --output out/engine-review
+          .venv/bin/python examples/compositing_review.py --output out/compositing-review
+          .venv/bin/python examples/hatch_review.py --output out/hatch-review
+          .venv/bin/python examples/clipping_review.py --output out/clipping-review
       - name: Diagram routing and label review
         run: |
           .venv/bin/python tools/benchmark_diagrams.py --repeat 1 --output out/diagram-benchmark.json
@@ -90,6 +114,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.dev2}/.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.dev2
         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.dev2' >&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.dev2}/CHANGELOG.md

@@ -1,5 +1,170 @@
 # Changelog
 
+## 4.0.0.dev2 — 2026-09-08
+
+Second development preview. Install explicitly with
+`python -m pip install "inklet==4.0.0.dev2"`; 3.1.0 remains stable.
+
+- Preserve open cubic segments through geometric clipping, using parameter
+  subdivision and bounded adaptive measurement sampling in the clip frame.
+- Add `window()` for nested, transformed visual clipping of all SVG/PDF/PNG
+  paint, including glyphs, images, markers, filled curves and rounded corners.
+  Keep window layout, painted bounds and authored child geometry distinct;
+  expose inherited clip regions and visibility filtering through resolution.
+- Preserve windows through document compilation/copying and account for hidden
+  content in page-bound and path-crossing diagnostics.
+- Reduce allocation in dense-line clipping; add an eight-panel rendering
+  review, independent backend checks and reproducible clipping/line benchmarks.
+
+
+- Share exact hatch-line geometry between SVG and PDF, with reusable local
+  coverage resources and independent shape clips. Preserve holes, transforms,
+  border styles and fill opacity without periodic tile seams or inherited
+  border settings affecting the fill.
+- Reuse hatch coverage across nearby shape sizes, retain explicit work limits,
+  and add an illustrated review plus repeated/distinct-size export benchmarks.
+
+- Correct PDF compositing for individual filled-and-stroked shapes, text halos
+  and vector brushes: group opacity fades their combined paint once.
+- Preserve palette and color-key PNG transparency in PDF, including partial
+  palette alpha and file-backed images.
+- Reuse subtree painted bounds and paint-count analysis within each PDF page
+  export; nested transparency groups no longer remeasure the same glyphs for
+  every ancestor. Keep inherited style/transform contexts separate and discard
+  the caches after export.
+- Add an illustrated compositing review, independent SVG/Poppler comparisons
+  and a nested-group workload to the rendering benchmark and CI checks.
+
+## 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.dev2}/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.dev2}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.5
 Name: inklet
-Version: 3.1.0
+Version: 4.0.0.dev2
 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,27 @@ 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.dev2** adds curve-preserving clipping, painted windows, improved PDF
+compositing and hatching, alongside 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.dev2"
+```
+
+[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.dev2)
+
+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.dev2}/README.md

@@ -29,6 +29,27 @@ 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.dev2** adds curve-preserving clipping, painted windows, improved PDF
+compositing and hatching, alongside 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.dev2"
+```
+
+[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.dev2)
+
+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.dev2}/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.dev2}/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`
 
@@ -457,6 +457,10 @@ One data glyph, centred on its own origin so `place()` lands it on the point it
 
 Put children at explicit coordinates, in millimetres.
 
+#### `window(items: 'Diagram | Iterable[Diagram]', region: 'Rect | Sequence[Point]', *, kind: 'str' = 'window', **style) -> 'Diagram'`
+
+Crop painted content to a fixed convex window, in local millimetres.
+
 #### `clip(items: 'Diagram | Iterable[Diagram]', region: 'Rect | Sequence[Point]', *, kind: 'str' = 'clip', strict: 'bool' = False, **style) -> 'Diagram'`
 
 Cut `items` down to `region`, in the coordinate frame you pass it in.
@@ -1058,9 +1062,9 @@ Flatten the tree into world transforms, keyed by node id.
 
 ## Core types and units
 
-#### `class Diagram(prim: 'Prim | None' = None, children: "tuple['Diagram', ...]" = (), transform: 'Affine' = Affine(a=1.0, b=0.0, c=0.0, d=1.0, e=0.0, f=0.0), style: 'Style' = Style(fill=None, stroke=None, stroke_width=None, stroke_dash=None, stroke_linecap=None, stroke_linejoin=None, opacity=None, fill_opacity=None, stroke_opacity=None, corner_radius=None, font_family=None, font_size=None, font_weight=None, font_style=None, text_fill=None, line_height=None, halo=None, halo_color=None), kind: 'str' = 'g', name: 'str | None' = None, id: 'str' = '', envelope_override: 'Envelope | None' = None, attached_to: 'tuple[str, ...]' = (), anchors: 'dict[str, Vec2]' = <factory>, notes: 'dict[str, object]' = <factory>, _cache: 'dict' = <factory>) -> None`
+#### `class Diagram(prim: 'Prim | None' = None, children: "tuple['Diagram', ...]" = (), transform: 'Affine' = Affine(a=1.0, b=0.0, c=0.0, d=1.0, e=0.0, f=0.0), style: 'Style' = Style(fill=None, stroke=None, stroke_width=None, stroke_dash=None, stroke_linecap=None, stroke_linejoin=None, opacity=None, fill_opacity=None, stroke_opacity=None, corner_radius=None, font_family=None, font_size=None, font_weight=None, font_style=None, text_fill=None, line_height=None, halo=None, halo_color=None), kind: 'str' = 'g', name: 'str | None' = None, id: 'str' = '', envelope_override: 'Envelope | None' = None, attached_to: 'tuple[str, ...]' = (), anchors: 'dict[str, Vec2]' = <factory>, notes: 'dict[str, object]' = <factory>, clip_region: 'tuple[Vec2, ...]' = (), _cache: 'dict' = <factory>) -> None`
 
-Diagram(prim: 'Prim | None' = None, children: "tuple['Diagram', ...]" = (), transform: 'Affine' = Affine(a=1.0, b=0.0, c=0.0, d=1.0, e=0.0, f=0.0), style: 'Style' = Style(fill=None, stroke=None, stroke_width=None, stroke_dash=None, stroke_linecap=None, stroke_linejoin=None, opacity=None, fill_opacity=None, stroke_opacity=None, corner_radius=None, font_family=None, font_size=None, font_weight=None, font_style=None, text_fill=None, line_height=None, halo=None, halo_color=None), kind: 'str' = 'g', name: 'str | None' = None, id: 'str' = '', envelope_override: 'Envelope | None' = None, attached_to: 'tuple[str, ...]' = (), anchors: 'dict[str, Vec2]' = <factory>, notes: 'dict[str, object]' = <factory>, _cache: 'dict' = <factory>)
+Diagram(prim: 'Prim | None' = None, children: "tuple['Diagram', ...]" = (), transform: 'Affine' = Affine(a=1.0, b=0.0, c=0.0, d=1.0, e=0.0, f=0.0), style: 'Style' = Style(fill=None, stroke=None, stroke_width=None, stroke_dash=None, stroke_linecap=None, stroke_linejoin=None, opacity=None, fill_opacity=None, stroke_opacity=None, corner_radius=None, font_family=None, font_size=None, font_weight=None, font_style=None, text_fill=None, line_height=None, halo=None, halo_color=None), kind: 'str' = 'g', name: 'str | None' = None, id: 'str' = '', envelope_override: 'Envelope | None' = None, attached_to: 'tuple[str, ...]' = (), anchors: 'dict[str, Vec2]' = <factory>, notes: 'dict[str, object]' = <factory>, clip_region: 'tuple[Vec2, ...]' = (), _cache: 'dict' = <factory>)
 
 * `extent(direction: 'Vec2') -> 'float'` -- How far this reaches along a direction, in the parent's frame. This is what stacking asks, and why a rotated shape packs tighter than its bbox.
 * `anchor(name: 'str', at: 'tuple[float, float] | Vec2') -> "'Diagram'"` -- Register a named point. A tuple is read as fractions of the local bounding box, (0, 0) being its top-left corner -- the natural way to point at an ear in a photograph.

inklet-4.0.0.dev2/docs/assets/research-preview/clipping-after.json

@@ -0,0 +1,119 @@
+{
+  "schema": "inklet.clipping-benchmark/1",
+  "python": "3.12.3",
+  "platform": "Linux-6.6.87.2-microsoft-standard-WSL2-x86_64-with-glibc2.39",
+  "source_sha256": "b4ded74e40916e536713f7589469a20bb25677587c03e83942cf6aeb7ecf0bd5",
+  "cases": [
+    {
+      "case": "line",
+      "runs": [
+        {
+          "clip_seconds": 0.09736313400208019,
+          "svg_seconds": 0.010083654022309929,
+          "pdf_seconds": 0.01944988899049349,
+          "total_seconds": 0.1268966770148836,
+          "svg_bytes": 76870,
+          "pdf_bytes": 36176
+        },
+        {
+          "clip_seconds": 0.09901987100602128,
+          "svg_seconds": 0.010495024005649611,
+          "pdf_seconds": 0.0206202779954765,
+          "total_seconds": 0.1301351730071474,
+          "svg_bytes": 76870,
+          "pdf_bytes": 36176
+        },
+        {
+          "clip_seconds": 0.10801237399573438,
+          "svg_seconds": 0.01182610000250861,
+          "pdf_seconds": 0.022811452014138922,
+          "total_seconds": 0.1426499260123819,
+          "svg_bytes": 76870,
+          "pdf_bytes": 36176
+        }
+      ],
+      "median": {
+        "clip_seconds": 0.09901987100602128,
+        "svg_seconds": 0.010495024005649611,
+        "pdf_seconds": 0.0206202779954765,
+        "total_seconds": 0.1301351730071474,
+        "svg_bytes": 76870,
+        "pdf_bytes": 36176
+      }
+    },
+    {
+      "case": "band",
+      "runs": [
+        {
+          "clip_seconds": 0.6217630119936075,
+          "svg_seconds": 0.05115153800579719,
+          "pdf_seconds": 0.10317503899568692,
+          "total_seconds": 0.7760895889950916,
+          "svg_bytes": 316513,
+          "pdf_bytes": 145203
+        },
+        {
+          "clip_seconds": 0.626939455018146,
+          "svg_seconds": 0.06268787098815665,
+          "pdf_seconds": 0.09176701598335057,
+          "total_seconds": 0.7813943419896532,
+          "svg_bytes": 316513,
+          "pdf_bytes": 145203
+        },
+        {
+          "clip_seconds": 0.6646606319991406,
+          "svg_seconds": 0.05158257801667787,
+          "pdf_seconds": 0.09825415699742734,
+          "total_seconds": 0.8144973670132458,
+          "svg_bytes": 316513,
+          "pdf_bytes": 145203
+        }
+      ],
+      "median": {
+        "clip_seconds": 0.626939455018146,
+        "svg_seconds": 0.05158257801667787,
+        "pdf_seconds": 0.09825415699742734,
+        "total_seconds": 0.7813943419896532,
+        "svg_bytes": 316513,
+        "pdf_bytes": 145203
+      }
+    },
+    {
+      "case": "curves",
+      "runs": [
+        {
+          "clip_seconds": 0.02900044500711374,
+          "svg_seconds": 0.0009433439990971237,
+          "pdf_seconds": 0.0009197680046781898,
+          "total_seconds": 0.030863557010889053,
+          "svg_bytes": 5248,
+          "pdf_bytes": 3319
+        },
+        {
+          "clip_seconds": 0.030080602009547874,
+          "svg_seconds": 0.0012863579904660583,
+          "pdf_seconds": 0.0010805090132635087,
+          "total_seconds": 0.03244746901327744,
+          "svg_bytes": 5248,
+          "pdf_bytes": 3319
+        },
+        {
+          "clip_seconds": 0.029620053013786674,
+          "svg_seconds": 0.0009497819992247969,
+          "pdf_seconds": 0.0013156150234863162,
+          "total_seconds": 0.03188545003649779,
+          "svg_bytes": 5248,
+          "pdf_bytes": 3319
+        }
+      ],
+      "median": {
+        "clip_seconds": 0.029620053013786674,
+        "svg_seconds": 0.0009497819992247969,
+        "pdf_seconds": 0.0010805090132635087,
+        "total_seconds": 0.03188545003649779,
+        "svg_bytes": 5248,
+        "pdf_bytes": 3319
+      }
+    }
+  ]
+}