inklet 4.0.0.dev9__tar.gz → 4.0.0.dev10__tar.gz

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/.github/workflows/publish.yml

@@ -6,7 +6,7 @@ on:
       tag:
         description: Published GitHub release tag
         required: true
-        default: v4.0.0.dev9
+        default: v4.0.0.dev10
         type: string
       dry_run:
         description: Validate release files without uploading to PyPI
@@ -43,7 +43,7 @@ jobs:
           RELEASE_TAG: ${{ inputs.tag }}
         run: |
           [[ "$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.dev9' >&2
+            echo 'Expected a stable or development tag such as v3.1.0 or v4.0.0.dev10' >&2
             exit 1
           }
           gh release view "$RELEASE_TAG" --json isDraft,isPrerelease > "$RUNNER_TEMP/release.json"

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 4.0.0.dev10 — 2026-09-12
+
+Tenth development preview: reproducible named label and callout editing.
+3.1.0 remains the stable release.
+
+- Edit string module captions, text components, keyed plot titles/text/callouts
+  and named composition annotations in the local layout editor.
+- Expose callout text, preferred side, physical clearance and leader visibility;
+  remeasure content and dependent connections through the Python compiler.
+- Save typed label identities and changed fields in layout schema 0.3, accepting
+  legacy 0.1/0.2 files, undo/redo, independent copies and shared definitions.
+- Report removed or incompatible labels individually; explicit discard preserves
+  compatible edits on the same object. Leave unedited source decisions live.
+- Add browser controls, source revision and two-width SVG/PDF roundtrip checks,
+  installed-package coverage and an illustrated guide and example.
+
 ## 4.0.0.dev9 — 2026-09-12
 
 Ninth development preview: mouse movement and proportional artwork scaling.

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: inklet
-Version: 4.0.0.dev9
+Version: 4.0.0.dev10
 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/latest/
@@ -81,16 +81,16 @@ their signatures and report schemas may change.
 
 ## 4.0 development preview
 
-**4.0.0.dev9** adds mouse movement and proportional artwork scaling to the
-local layout editor. Drag named objects and groups, use corner handles, undo
-gestures, and save choices that reproduce through the Python compiler.
+**4.0.0.dev10** adds named label and callout editing to the local layout
+editor. Edit text and callout preferences, move and scale content, undo changes,
+and save choices that reproduce through the Python compiler.
 ```sh
-python -m pip install "inklet==4.0.0.dev9"
+python -m pip install "inklet==4.0.0.dev10"
 ```
 
 [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.dev9)
+[Release notes](https://github.com/Mapika/inklet/releases/tag/v4.0.0.dev10)
 
 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,

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/README.md

@@ -31,16 +31,16 @@ their signatures and report schemas may change.
 
 ## 4.0 development preview
 
-**4.0.0.dev9** adds mouse movement and proportional artwork scaling to the
-local layout editor. Drag named objects and groups, use corner handles, undo
-gestures, and save choices that reproduce through the Python compiler.
+**4.0.0.dev10** adds named label and callout editing to the local layout
+editor. Edit text and callout preferences, move and scale content, undo changes,
+and save choices that reproduce through the Python compiler.
 ```sh
-python -m pip install "inklet==4.0.0.dev9"
+python -m pip install "inklet==4.0.0.dev10"
 ```
 
 [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.dev9)
+[Release notes](https://github.com/Mapika/inklet/releases/tag/v4.0.0.dev10)
 
 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,

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/docs/api.md

@@ -225,12 +225,12 @@ A figure assembled from named children and measured expressions.
 * `instantiate(**items)` -- Create an independent recipe, filling required slots and replacing defaults.
 * `configure(*, width=None, height=None, unit=None, fit_top=None)` -- Atomically update authored page dimensions or coordinate units.
 * `place(name, **placement)` -- Edit a child's placement without replacing its content or named links.
-* `layout_overrides(reference)` -- Capture changed placements and page fields against a matching reference.
+* `layout_overrides(reference)` -- Capture changed layout and compatible named labels against a reference.
 * `with_layout_overrides(value, *, missing='error')` -- Return an independent edited recipe and a reconciliation report.
 * `port(name, target)` -- Expose a child's name:anchor as a reusable composition attachment point.
 * `constrain(value, *, minimum=0, message='composition needs more space')` -- Require an expression to meet a minimum; fail before drawing.
 * `link(source, target, **options)` -- Route a branch or return between named children (`name:port`).
-* `annotate(target, text, **options)` -- Place a measured callout after every child and connection exists.
+* `annotate(target, text, **options)` -- Place a measured callout; a unique name enables saved label editing.
 * `signature(trail=())`
 * `render(context, width=None, height=None)`
 

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/docs/development-preview.md

@@ -1,6 +1,6 @@
-# Inklet 4.0.0.dev9
+# Inklet 4.0.0.dev10
 
-The ninth 4.0 development release includes the linked plotting, mapping,
+The tenth 4.0 development release includes the linked plotting, mapping,
 engineering and scientific workflows developed since 3.1.0. It is an installable
 snapshot for trying real examples and reporting problems. **3.1.0 remains the
 stable release.** The [4.0 roadmap](roadmap.md) still has open work.
@@ -8,7 +8,7 @@ stable release.** The [4.0 roadmap](roadmap.md) still has open work.
 ```sh
 python -m venv .venv
 source .venv/bin/activate
-python -m pip install "inklet==4.0.0.dev9"
+python -m pip install "inklet==4.0.0.dev10"
 ```
 
 On Windows PowerShell, activate with `.venv\Scripts\Activate.ps1` instead.
@@ -19,9 +19,9 @@ stable releases; see its [installation documentation](https://pip.pypa.io/en/sta
 Optional extras can be installed with the same pin:
 
 ```sh
-python -m pip install "inklet[render,pandas,polars]==4.0.0.dev9"
+python -m pip install "inklet[render,pandas,polars]==4.0.0.dev10"
 # Add calibrated volumes and TIFF workflows when needed:
-python -m pip install "inklet[volume,render]==4.0.0.dev9"
+python -m pip install "inklet[volume,render]==4.0.0.dev10"
 ```
 
 The core preview needs no browser server, NumPy, pandas, Polars or Blender.
@@ -29,7 +29,26 @@ Opening the generated HTML requires a browser. PNG/PDF exports from browser
 figures use separate Chrome/Chromium and Pillow; native Diagram exports retain
 their existing requirements. See [installation](installation.md).
 
-## Mouse movement and scaling in dev9
+## Named labels and callouts in dev10
+
+The [local layout editor](layout-editor.md#edit-labels-and-callouts) now edits
+string module captions, text components, keyed plot titles/text/callouts and
+named composition annotations. Callouts expose preferred side, physical
+clearance and leader visibility. Text changes remeasure content and update
+dependent layout and connections through Python.
+
+Saved choices contain explicit label keys and kinds. Reordering instructions
+preserves identity; removing a key or changing its kind reports an incompatible
+label. Explicit discard retains compatible edits on the same object. Shared
+definitions share text decisions, while unedited source fields remain live.
+
+![Named callout controls and the compiled figure](assets/guides/layout-editor-labels.png)
+
+New files use layout schema 0.3; schemas 0.1 and 0.2 still load. Undo/redo,
+reopening and matching SVG/PDF export include text edits. Axis labels, individual
+callout dragging, camera editing and general object relationships remain open.
+
+## Mouse movement and scaling retained from dev9
 
 The [layout editor](layout-editor.md) now supports direct mouse movement and
 proportional corner scaling of named objects and groups. Alt-click selects a
@@ -44,7 +63,7 @@ retain their separate typography-preserving layout behavior.
 
 ![Mouse selection and proportional scaling in the local editor](assets/guides/layout-editor-gestures.png)
 
-New layout files use schema 0.2 for explicit artwork scale. Dev7/dev8 schema 0.1
+Dev9 introduced schema 0.2 for explicit artwork scale. Dev7/dev8 schema 0.1
 files still load. Named composition objects are editable; individual plot marks,
 axis labels, connector segments and camera parameters remain outside this scope.
 
@@ -63,8 +82,8 @@ remain consistent across repeated edits and resets.
 
 ![The local browser layout inspector](assets/guides/layout-editor.png)
 
-This inspector requires its local Python session. It covers composition layout;
-label content, individual plot marks and cameras remain separate work.
+This inspector requires its local Python session. Named label editing is added
+in dev10; individual plot marks and cameras remain separate work.
 The existing standalone viewers and linked-plot appearance editor retain their
 current scope.
 
@@ -181,7 +200,7 @@ The wheel contains the library. To obtain recipes and fixtures, use the matching
 release checkout or source archive:
 
 ```sh
-git clone --branch v4.0.0.dev9 https://github.com/Mapika/inklet.git
+git clone --branch v4.0.0.dev10 https://github.com/Mapika/inklet.git
 cd inklet
 python -m pip install -e '.[render]'
 python examples/v4/regional_report.py --renderer compiled --editor --output out/regional

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/docs/layout-editor.md

@@ -1,6 +1,6 @@
 # Local layout editor
 
-Available since **4.0.0.dev8**, with mouse gestures in **4.0.0.dev9**, under `inklet.experimental.layout_editor`. Adjust
+Available since **4.0.0.dev8**, with mouse gestures in **4.0.0.dev9** and named label editing in **4.0.0.dev10**, under `inklet.experimental.layout_editor`. Adjust
 named placements and dimensions in a browser while Python recompiles the
 actual composition. The preview and downloaded SVG/PDF come from the same
 compiled figure, including plots, nested diagrams and native 3D content.
@@ -75,10 +75,50 @@ marks, ticks, axis labels and connector segments remain part of their owning
 plot or diagram. Scaling and movement do not remove authored constraints or
 top-fitting behavior; dependent content can reflow when the compiler rebuilds.
 
+## Edit labels and callouts
+
+![Editing a named plot callout with text, side, clearance and leader controls](assets/guides/layout-editor-labels.png)
+
+Select a composition child, then edit its **Label** fields and choose **Apply
+changes**. The editor supports text components created with `component(i.text,
+...)`, string module captions, and plot `title`, `text` and `annotate`
+instructions with an explicit string `key`. For composition callouts, supply a
+unique `name` and select the composition that owns the callout.
+
+```python
+recipe['chart'].annotate(1, 2, 'Reference observation', key='observation', side='s', clear=4)
+recipe.annotate('caption', 'Measured response', name='response-note', side='e', clear=3)
+editor.command('refresh')
+editor.command('edit', {
+    'path': '/chart',
+    'labels': {'observation': {'kind': 'plot-annotate', 'text': 'Reviewed observation', 'side': 'sw'}},
+})
+```
+
+Callouts expose their preferred compass side, clearance in physical millimetres,
+and leader visibility. Automatic placement can choose another side to avoid
+conflicts. Plot clearance can be left blank to use its automatic value. This
+increment edits callout content and placement preferences; it does not add free
+mouse dragging of individual callouts or axis-label editing.
+
+A label's identity is its composition path, explicit key and kind. For example,
+`/chart` plus `observation` identifies a plot annotation even when its instruction
+moves in the recipe. Replacing that key with a different instruction kind is an
+incompatible target. A removed or incompatible label is reported as
+`/chart#observation`; explicit discard drops that label's edits while retaining
+compatible placement and label edits on the same chart. Renaming a path or key
+changes its identity. Reusing the same key and kind declares the same label.
+
+Text changes are measured by the Python compiler: longer module captions can
+move dependent modules and reroute their connections. Unedited labels, data
+coordinates, styling and other source choices remain live. Shared definitions
+share label edits; use an independent recipe copy for independent captions.
+Undo/redo, reset, saved JSON and SVG/PDF exports include the label edits.
+
 ## Edit and review
 
 Choose a named path in **Content**, enter the fields you want to change, then
-select **Apply layout**. Other fields retain their definitions.
+select **Apply changes**. Other fields retain their definitions.
 
 - Child placement fields are X, Y, anchor, width, height and uniform scale. Numbers use the
   containing composition's coordinate unit. For plots, width and height describe

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/docs/layout-overrides.md

@@ -1,6 +1,6 @@
 # Save and restore layout choices
 
-Available since **4.0.0.dev7**; uniform artwork scale is added in **dev9**. Save placement and dimension edits separately from
+Available since **4.0.0.dev7**; uniform artwork scale is added in **dev9**, named text and callout decisions in **dev10**. Save placement and dimension edits separately from
 a [composition recipe](composition-recipes.md), then restore those choices
 when its data, labels or content change. The saved JSON records only differences
 from a reference recipe. Unedited source decisions remain in control.
@@ -21,7 +21,7 @@ Python APIs below or the [local inspector](layout-editor.md) in dev8. This forma
 
 Keep a reference recipe, copy it, then edit placements. The reference and edited
 recipe must have the same named composition structure when capturing changes.
-Content and styles can differ; they are not serialized into the layout file.
+Supported named label differences are captured too. Other content and styles are not serialized into the layout file.
 
 ```python
 import json
@@ -52,6 +52,25 @@ identity within the recipe hierarchy. Renaming or moving a target changes its
 identity. Definitions hidden inside component factories or other BuildSpecs
 are not traversed.
 
+## Named label decisions
+
+Changed string module captions and text components are captured alongside layout.
+Plot titles, text and annotations require explicit string instruction keys;
+composition annotations require unique names. See the [label editor](layout-editor.md#edit-labels-and-callouts)
+for controls, identity rules and an executable example. Captures compare only
+matching label keys and kinds; they do not serialize added or removed content.
+
+A saved label entry includes its kind and only the fields that changed:
+
+```json
+{"schema":"inklet.composition-layout/0.3","targets":{"/caption":{"labels":{"label":{"kind":"module-label","text":"Reviewed response"}}}}}
+```
+
+Readers accept legacy schemas 0.1 and 0.2. New captures use 0.3; older readers
+must be upgraded before opening them. Label fields are rejected under older
+schema identifiers. Removed/incompatible labels appear as `path#key` in the
+orphan report. Explicit `missing='drop'` retains compatible edits on that path.
+
 ## Restore on the current recipe
 
 ```python
@@ -85,7 +104,7 @@ updated_figure = render(updated)
 updated_figure.save('updated.svg')
 ```
 
-The file stores layout decisions, not content, datasets, labels, plot styles,
+The file stores layout and supported label decisions, not datasets, plot styles,
 links, ports, constraints, factories or camera parameters. Keep the Python
 recipe and its assets alongside it. The containing document can supply its own
 render dimensions; restoring authored page dimensions does not override that
@@ -123,11 +142,12 @@ of 32 operations. Malformed files, nonfinite numbers, invalid properties and
 contradictory edits to a shared nested definition are rejected, including when
 `missing='drop'` is used.
 
-New files use `inklet.composition-layout/0.2`, which adds a positive uniform
-artwork scale. The loader also accepts `inklet.composition-layout/0.1` files
-from dev7/dev8; those cannot contain scale fields. Unknown schemas are rejected.
-Upgrade older readers before opening a new 0.2 file. The file is a JSON object with `schema` and `targets`; each target has
-changed `placement` and/or `page` fields. It is a development-preview format,
+New files use `inklet.composition-layout/0.3`, adding named label decisions to
+0.2's positive uniform artwork scale. The loader also accepts 0.1 files from
+dev7/dev8 (without scale) and 0.2 files from dev9 (without labels). Unknown
+schemas are rejected. Upgrade older readers before opening a 0.3 file.
+The JSON object contains `schema` and `targets`; each target has changed
+`placement`, `page` and/or `labels` fields. This development-preview format is
 not a general Python object serializer or an asset manifest.
 
 ## Review revised content

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/docs/roadmap.md

@@ -60,8 +60,10 @@ Dev8 adds a [local layout inspector](layout-editor.md) backed by Python
 compilation, with saved choices, undo/redo and explicit source refresh.
 Dev9 adds mouse movement, proportional artwork scaling and keyboard nudges
 for named composition children, with preserved measured positions and saved
-choices. Serialized project templates, asset manifests, shared selection
-relationships, label/camera editing and finer-grained manipulation remain open. Subsequent work
+choices. Dev10 adds saved named text and callout editing across modules, text
+components, keyed plot instructions and composition annotations, including typed
+identity reconciliation. Serialized project templates, asset manifests, shared selection
+relationships, axis-label/camera editing and finer-grained manipulation remain open. Subsequent work
 should extend authoring and cross-content identity beyond this bounded inspector.
 
 ## Who this should serve

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/examples/layout_editor.py

@@ -10,6 +10,7 @@ def main():
     parser.add_argument('--port',type=int,default=0,help='Local port; 0 chooses an available port')
     args=parser.parse_args()
     reports,_=make_reports()
+    reports[0]['chart'].annotate(2,3,'Reference observation',key='observation',side='s',clear=4)
     with LayoutEditor(reports[0],preset='scientific.general').start(port=args.port) as editor:
         print(f'Open {editor.url} — press Ctrl+C to stop.',flush=True)
         try:threading.Event().wait()

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "inklet"
-version = "4.0.0.dev9"
+version = "4.0.0.dev10"
 description = "Scientific figures with live data, measured layout, and consistent vector exports."
 readme = "README.md"
 authors = [{name = "Mark Marosi"}]

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/src/inklet/__init__.py

@@ -470,4 +470,4 @@ __all__ = [
     "mm", "pt", "COLUMN_SINGLE", "COLUMN_DOUBLE",
 ]
 
-__version__ = "4.0.0.dev9"
+__version__ = "4.0.0.dev10"

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/src/inklet/document/composition.py

@@ -193,10 +193,10 @@ class Composition(BuildSpec):
         raise KeyError(name)
 
     def layout_overrides(self, reference):
-        """Capture changed placements and page fields against a matching reference.
+        """Capture changed layout and compatible named labels against a reference.
 
         Return JSON-compatible, versioned decisions keyed by named child paths.
-        Content, styles, data, links and constraints remain in the Python recipe.
+        Other content, styles, data, links and constraints remain in Python.
         """
         from .layout_overrides import capture
         return capture(self, reference)
@@ -234,7 +234,12 @@ class Composition(BuildSpec):
         return self
 
     def annotate(self, target, text, **options):
-        """Place a measured callout after every child and connection exists."""
+        """Place a measured callout; a unique name enables saved label editing."""
+        name = options.get('name')
+        if name is not None:
+            if not isinstance(name,str) or not name: raise ValueError('annotation name must be a nonempty string')
+            if any(opts.get('name')==name for _,_,opts in self._annotations):
+                raise LayoutError(f'duplicate annotation name {name!r}')
         self._annotations.append((target, text, freeze(options)))
         return self
 

inklet-4.0.0.dev10/src/inklet/document/label_overrides.py

@@ -0,0 +1,91 @@
+"""Explicit text targets within named recipes; never infer identity from ink."""
+from __future__ import annotations
+
+import math
+
+from .spec import ComponentSpec, PlotSpec
+from .module import ModuleSpec
+
+
+def targets(item):
+    """Return keyed, typed label controls and internal replacement locations."""
+    from .. import text
+    from .composition import Composition
+    found = {}
+
+    def add(key, kind, value, location, options=None):
+        if not isinstance(key, str) or not key or not isinstance(value, str): return
+        if key in found: raise ValueError(f'duplicate editable label key {key!r}')
+        fields = dict(kind=kind, text=value)
+        if options is not None:
+            from ..core import mm
+            clear = options.get('clear')
+            fields.update(side=options.get('side', 'n'), leader=options.get('leader', True))
+            # A measured clearance remains authored until explicitly replaced.
+            from .composition import LayoutValue
+            if not isinstance(clear, LayoutValue): fields['clear'] = None if clear is None else mm(clear)
+        found[key] = (fields, location)
+
+    if isinstance(item, ModuleSpec): add('label', 'module-label', item.label, ('module',))
+    elif isinstance(item, ComponentSpec) and item.factory is text:
+        add('text', 'component-text', item.args[0] if item.args else item.kwargs.get('content'), ('component',))
+    elif isinstance(item, PlotSpec):
+        for index, (key, method, args, options) in enumerate(item._steps):
+            if method not in ('title', 'text', 'annotate'): continue
+            position = 0 if method == 'title' else 2
+            keyword = 'text' if method == 'annotate' else 'content'
+            value = args[position] if len(args)>position else options.get(keyword)
+            add(key, 'plot-'+method, value, ('plot', index, position, keyword),
+                options if method == 'annotate' else None)
+    elif isinstance(item, Composition):
+        for index, (_, value, options) in enumerate(item._annotations):
+            add(options.get('name'), 'composition-annotation', value, ('annotation', index),
+                {'clear':2, **options})
+    return found
+
+
+def validate(value):
+    if not isinstance(value, dict) or not value: raise ValueError('labels must be a nonempty object')
+    result = {}
+    for key, fields in value.items():
+        if not isinstance(key, str) or not key or not isinstance(fields, dict):
+            raise ValueError('labels require nonempty string keys and field objects')
+        kind = fields.get('kind')
+        allowed = {'kind', 'text'}
+        if kind in ('plot-annotate', 'composition-annotation'): allowed |= {'side', 'clear', 'leader'}
+        if (kind not in ('module-label','component-text','plot-title','plot-text','plot-annotate','composition-annotation')
+                or not set(fields)<=allowed or len(fields)<2):
+            raise ValueError('invalid label kind or fields')
+        for name, val in fields.items():
+            if name=='text' and not isinstance(val, str): raise ValueError('label text must be a string')
+            if name=='side' and val not in ('n','ne','e','se','s','sw','w','nw'):
+                raise ValueError('invalid annotation side')
+            if name=='leader' and type(val) is not bool: raise ValueError('label leader must be a boolean')
+            if name=='clear' and not (val is None and kind=='plot-annotate'):
+                if type(val) not in (int,float) or not math.isfinite(val) or val<0:
+                    raise ValueError('label clearance must be finite nonnegative millimetres')
+        result[key] = dict(fields)
+    return result
+
+
+def apply(item, edits):
+    available = targets(item)
+    for key, fields in edits.items():
+        current, location = available[key]
+        changes = {k:v for k,v in fields.items() if k!='kind'}
+        value = changes.pop('text', current['text'])
+        if location[0]=='module': item.configure(value)
+        elif location[0]=='component':
+            if item.args: item.args = (value, *item.args[1:])
+            else: item.kwargs['content'] = value
+        elif location[0]=='plot':
+            _, index, position, keyword = location
+            found, method, args, kwargs = item._steps[index]
+            args, kwargs = list(args), dict(kwargs)
+            if len(args)>position: args[position] = value
+            else: kwargs[keyword] = value
+            item._steps[index] = (found, method, tuple(args), kwargs | changes)
+        else:
+            _, index = location
+            target, _, options = item._annotations[index]
+            item._annotations[index] = (target, value, options | changes)

{inklet-4.0.0.dev9 → inklet-4.0.0.dev10}/src/inklet/document/layout_overrides.py

@@ -1,4 +1,4 @@
-"""Portable placement decisions for named compositions, separate from content."""
+"""Portable layout and text decisions for named composition recipes."""
 from __future__ import annotations
 
 import math
@@ -6,8 +6,10 @@ import re
 
 from .compiler import LayoutError
 from .spec import length
+from . import label_overrides as labels
 
-SCHEMA = 'inklet.composition-layout/0.2'
+SCHEMA = 'inklet.composition-layout/0.3'
+SCALE_SCHEMA = 'inklet.composition-layout/0.2'
 LEGACY_SCHEMA = 'inklet.composition-layout/0.1'
 _PLACEMENT = {'x', 'y', 'anchor', 'width', 'height', 'scale'}
 _PAGE = {'width', 'height', 'unit', 'fit_top'}
@@ -91,7 +93,7 @@ def _page(values):
 
 
 def capture(recipe, reference):
-    """Record only changed layout fields; leave unedited source decisions live."""
+    """Record changed layout and compatible named labels; keep unedited fields live."""
     from .composition import Composition
     if not isinstance(reference,Composition): raise TypeError('reference must be a Composition')
     current, before = _targets(recipe), _targets(reference)
@@ -113,6 +115,13 @@ def capture(recipe, reference):
             old = _page({k:getattr(old_item,k) for k in sorted(_PAGE)})
             changed = {k:v for k,v in now.items() if v!=old[k]}
             if changed: entry['page'] = changed
+        current_labels, old_labels = labels.targets(item), labels.targets(old_item)
+        changed_labels = {}
+        for key,(fields,_) in current_labels.items():
+            if key not in old_labels or fields['kind']!=old_labels[key][0]['kind']: continue
+            changed = {k:v for k,v in fields.items() if k!='kind' and v!=old_labels[key][0].get(k, object())}
+            if changed: changed_labels[key] = {'kind':fields['kind'], **changed}
+        if changed_labels: entry['labels'] = changed_labels
         if entry: edits[path] = entry
     return {'schema':SCHEMA,'targets':edits}
 
@@ -129,7 +138,7 @@ def apply(recipe, value, *, missing='error'):
     """Validate all edits, reconcile stable names, then edit an independent copy."""
     from .composition import Composition
     if missing not in ('error','drop'): raise ValueError('missing policy must be error or drop')
-    if (not isinstance(value,dict) or set(value)!={'schema','targets'} or value['schema'] not in (SCHEMA,LEGACY_SCHEMA)
+    if (not isinstance(value,dict) or set(value)!={'schema','targets'} or value['schema'] not in (SCHEMA,SCALE_SCHEMA,LEGACY_SCHEMA)
             or not isinstance(value['targets'],dict)):
         raise ValueError('invalid composition layout overrides')
     targets = _targets(recipe)
@@ -137,7 +146,7 @@ def apply(recipe, value, *, missing='error'):
     for path,entry in value['targets'].items():
         if not isinstance(path,str) or not re.fullmatch(r'/(?:'+_NAME+r'(?:/'+_NAME+r')*)?',path):
             raise ValueError('layout targets require absolute named composition paths')
-        if not isinstance(entry,dict) or not entry or not set(entry)<={'placement','page'}:
+        if not isinstance(entry,dict) or not entry or not set(entry)<={'placement','page','labels'}:
             raise ValueError(f'invalid layout target properties: {path}')
         options = {}
         if 'placement' in entry:
@@ -145,6 +154,9 @@ def apply(recipe, value, *, missing='error'):
             if value['schema']==LEGACY_SCHEMA and 'scale' in options['placement']:
                 raise ValueError('scale requires composition layout schema 0.2')
         if 'page' in entry: options['page'] = _page(entry['page'])
+        if 'labels' in entry:
+            if value['schema']!=SCHEMA: raise ValueError('labels require composition layout schema 0.3')
+            options['labels'] = labels.validate(entry['labels'])
         target = targets.get(path)
         invalid = target is None
         if target is not None:
@@ -154,7 +166,17 @@ def apply(recipe, value, *, missing='error'):
                 names = {p.name for p in parent._parts}
                 invalid |= any(ref not in names for val in options['placement'].values() for ref in _references(val))
         if invalid: orphaned.append(path)
-        else: prepared[path] = options
+        else:
+            if 'labels' in options:
+                available = labels.targets(item)
+                compatible = {}
+                for key,fields in options['labels'].items():
+                    if key not in available or fields['kind']!=available[key][0]['kind']:
+                        orphaned.append(path+'#'+key)
+                    else: compatible[key] = fields
+                if compatible: options['labels'] = compatible
+                else: options.pop('labels')
+            if options: prepared[path] = options
     orphaned.sort()
     if orphaned and missing=='error': raise LayoutError('orphaned layout targets: '+', '.join(orphaned))
     # One nested definition may occur at several named paths. Contradictory
@@ -163,7 +185,9 @@ def apply(recipe, value, *, missing='error'):
     for path,options in prepared.items():
         parent,part,item = targets[path]
         for group,fields in options.items():
-            owner = (id(item),None) if group=='page' else (id(parent),part.name)
+            owner = (id(item),None) if group in ('page','labels') else (id(parent),part.name)
+            if group=='labels':
+                fields = {(label,key):val for label,edits in fields.items() for key,val in edits.items()}
             for key,val in fields.items():
                 identity = (*owner,group,key)
                 if identity in assigned and assigned[identity]!=val:
@@ -173,6 +197,7 @@ def apply(recipe, value, *, missing='error'):
     copied = _targets(result)
     for path,options in prepared.items():
         parent,part,item = copied[path]
+        if 'labels' in options: labels.apply(item,options['labels'])
         if 'page' in options: item.configure(**options['page'])
         if 'placement' in options: parent.place(part.name,**options['placement'])
     return result, {'orphaned_targets':orphaned,'missing_policy':missing}