Creative Capability Bridge

Creative Capability Bridge (CCB) is a versioned protocol, adapter toolkit, and reference plan builder for expressing common creative operations once and translating them for different applications.

The current protocol supports text creation, text updates, and explicit transforms through Blender, Inkscape, and GIMP 3 adapters. It adds transactional execution, rollback backups, resumable and selective plans, semantic document diffs, coordinate normalization, policy profiles, dependency-aware multi-document pipelines, adapter conformance checks, and optional Ed25519 signatures for bundles and receipts. Version 1.6.1 tightens supported-adapter evidence and GIMP saved-document acceptance. The separate PNG export contract added in 1.6.0 uses Inkscape; it does not add universal export support.

Open the plan builder

Why this exists

Creative applications repeatedly implement text, transforms, colors, exports, asset browsers, and similar capabilities with different interaction models. CCB separates the user's intent from application-specific commands:

reference interface or JSON authoring
                 ↓
       CCB protocol v1 plan
                 ↓
     validate and negotiate support
                 ↓
 Blender adapter       Inkscape adapter       GIMP 3 adapter
 background Python     SVG + optional render  Script-Fu batch

The protocol is the stable center. Applications remain installed separately, upstream code is not forked, and every output path is explicit.

Features

• Export restricted SVG to PNG through an installed Inkscape renderer, with explicit output and a structural receipt.

• Separate exact measured application versions from target version ranges; see compatibility evidence.

• Add ccb preflight for input hashes, output/receipt collisions, font-file availability, target lifecycles, and optional policy or document inspection.

• Add ccb compare-plans for metadata fields, added/removed/changed operation fields, and operation order without printing raw parameter values or file paths.

• Add validated local JSON plan import and operation editing/reordering/removal to the reference builder.

• Add target-order review and bounded session Undo/Redo; preserve coordinate metadata through builder edits.

• Keep execution explicit and preserve existing inputs and outputs during review.

Current capabilities

Capability	Blender	Inkscape	GIMP 3
Create text	Yes	Yes	Yes
Update bridge-managed or identified text	Yes	Yes	Yes
Font family request	Recorded; native resolution is application-dependent	SVG font-family	Exact installed GIMP font resource name
Font size, alignment, fill	Yes	Yes	Yes
Position and Z rotation	Yes	Yes	Yes
X/Y scale	Yes	Yes	Yes
Z position and scale	Yes	Not applicable	Not applicable
Read-only structural inspection	Yes	Yes	Yes
Native conformance fixture	Yes	Yes	Dedicated GIMP 3 saved-XCF gate; see measured evidence

Use ccb capabilities --json for the machine-readable manifests.

Portable workflow

CCB adds reviewable stages around execution:

ccb inspect source.svg
ccb explain plan.json
ccb lint plan.json --document source.svg
ccb compatibility examples/portable-text.json
ccb retarget examples/portable-text.json --adapter inkscape --output inkscape-plan.json
ccb bundle create inkscape-plan.json project.ccb.zip --asset LICENSE.txt --fallback-font sans-serif
ccb bundle verify project.ccb.zip
ccb bundle extract project.ccb.zip unpacked-project
ccb execute inkscape-plan.json --receipt receipt.json
ccb verify-receipt receipt.json
ccb compare-receipts receipt-a.json receipt-b.json
ccb diff source.svg output.svg
ccb normalize plan.json
ccb conformance inkscape --native

• inspect reads .svg metadata directly and uses Blender's background mode for .blend; it does not save the source.
• explain lists files read/created, replacement state, created/modified targets, requirements, and known approximations.
• lint checks operation order and target lifecycles; with --document, it confirms referenced targets through read-only inspection.
• Bundles contain plan.json, optional assets/, and a manifest with SHA-256 hashes, license notes, fallback fonts, and archive-relative paths.
• bundle extract verifies hashes and paths first, then writes only into a new destination directory.
• Receipts record tool/application versions, hashes, operations, warnings, platform, and elapsed time after a successful execution. They contain paths and may expose local directory names, so review them before sharing.
• verify-receipt re-hashes the recorded input and output to detect missing or changed files.
• adapter: "auto" is valid for compatibility and retargeting only. Execution still requires a concrete, validated adapter plan.
• Every execution is staged into a temporary same-format document and inspected before an atomic destination replacement. Existing outputs receive a retained rollback backup.
• Operation IDs and tags enable --only, --skip, and --from; --state plus --resume verifies the output hash before continuing from recorded checkpoints.
• Policy profiles constrain adapters, capabilities, output roots, operation counts, input size, replacement, inspection, receipts, and signed-bundle requirements.
• Pipeline files order multiple plans through explicit depends_on relationships and reject missing or cyclic dependencies.
• Bundles and receipts can be signed and verified with local Ed25519 key pairs. Private keys are never placed in bundles or receipts.

GIMP text plans use the current GIMP context font when no font is specified. An explicit font_family must name an installed GIMP font resource exactly (for example, DejaVu Sans Book); missing resources fail rather than silently substituting a font. GIMP support is limited to identified top-level layers. Translation preserves omitted axes; scaling rounds dimensions to whole pixels and may rasterize text. Rotation uses the layer center and may lose raster detail. These are adapter-specific semantics, not interchangeable vector/object transforms. Native fixture success is not a guarantee for arbitrary XCF files.

Three-minute start

Requires Python 3.10 or newer. Native execution requires the selected application on PATH; GIMP support targets GIMP 3's bundled Script-Fu batch interpreter. Inkscape is optional unless native rendering is requested because ordinary SVG editing is handled directly.

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install .
ccb validate examples/inkscape-text.json
ccb preview examples/inkscape-text.json
ccb execute examples/inkscape-text.json

The example writes examples/output/inkscape-text.svg. It does not change an input file.

For Blender:

ccb doctor
ccb preview examples/blender-text.json
ccb execute examples/blender-text.json

For GIMP 3:

ccb preview examples/gimp-text.json
ccb conformance gimp --native
ccb execute examples/gimp-text.json --receipt gimp-receipt.json

For guarded, resumable work:

ccb key generate ccb-private.pem ccb-public.pem
ccb bundle create plan.json project.ccb.zip --signing-key ccb-private.pem
ccb bundle verify project.ccb.zip --public-key ccb-public.pem --require-signature
ccb execute plan.json --only titles --state run.state.json --receipt run.json
ccb execute plan.json --state run.state.json --resume --receipt resumed.json
ccb policy check plan.json examples/safe-policy.json --receipt run.json
ccb pipeline validate examples/two-document-pipeline.json

The browser plan builder creates JSON locally. It does not upload documents or execute applications.

Plan format

{
  "version": 1,
  "adapter": "inkscape",
  "input": null,
  "output": "output.svg",
  "operations": [
    {
      "id": "create-title",
      "tags": ["titles"],
      "capability": "text.create",
      "target": "title",
      "parameters": {
        "content": "A common interface",
        "font_family": "Liberation Sans",
        "font_size": 48,
        "alignment": "center",
        "fill": "#1D2522",
        "x": 600,
        "y": 300
      }
    }
  ],
  "coordinate_space": {
    "unit": "px",
    "origin": "top-left",
    "y_axis": "down",
    "dpi": 96,
    "width": 1200,
    "height": 800
  }
}

Paths are resolved relative to the plan file. Input and output must differ. Existing outputs are refused unless the user explicitly passes --replace; that flag never authorizes changing the input. Operation IDs and tags are optional, so existing version 1 plans remain valid.

See protocol details and adapter authoring.

Architecture and safety

• Plans are plain JSON and can be reviewed before execution.
• Unknown operations, fields, adapters, dimensions, and unsafe same-file outputs fail closed.
• Bundle verification rejects duplicate or traversal paths and validates declared lengths and SHA-256 hashes before use.
• Inkscape editing uses its documented SVG format; optional native preview invokes the Inkscape CLI.
• Blender receives a generated background Python script containing a base64-encoded, already-validated plan.
• GIMP 3 receives a generated Script-Fu program through its documented noninteractive batch interpreter.
• Execution writes and inspects a temporary document before atomically placing it at the requested output. A replacement preserves the prior output as a separate rollback file.
• Ed25519 signatures authenticate canonical bundle manifests and receipt payloads when the operator supplies a trusted public key.
• Originals are never overwritten.
• No network request, telemetry, cloud service, model call, or runtime AI is used.
• A plan can modify or create creative documents, so review plans from untrusted sources before execution.

Read the complete security model.

Honest limitations

• Version 1 is file-oriented. It does not synchronize with a selection in an already-open GUI.
• Inspection exposes supported metadata, not a complete application scene graph, and cannot guarantee that every native object is semantically editable.
• Unsigned bundles verify integrity but not publisher identity or asset licensing; license notes remain operator-supplied. Optional signatures prove possession of a private key, not the real-world identity behind that key.
• Receipts record and hash one local execution. Optional signatures protect the receipt payload from later alteration but do not independently prove that the native application behaved honestly.
• Blender, Inkscape, and GIMP are not interchangeable. CCB exposes a common core and rejects unsupported dimensions rather than inventing equivalence.
• The Blender font-family field records the requested family because reliable cross-platform font resolution needs a future explicit font-mapping contract.
• Inkscape document edits are deterministic SVG operations; Inkscape itself is invoked only for optional native preview rendering.
• Coordinate conversion covers pixels, points, physical units, Blender units, origins, and Y-axis direction. Arbitrary pivots and full transform-order negotiation remain outside protocol v1.
• GIMP inspection reports portable layer identifiers, dimensions, and offsets; it does not expose every XCF property or claim full semantic equivalence with SVG or Blender scenes.
• Intuitiveness requires real user research and cannot be established by automated tests alone.
• Native compatibility is version-sensitive. See the compatibility policy.

Research roadmap

These are potential directions under investigation, not promised features or release dates:

1. Live adapter sessions — small, local in-application bridges for selection, state, undo groups, transactions, and event synchronization.
2. FreeCAD and additional adapters — only after their semantics can be expressed through the conformance suite without hiding important differences.
3. Additional capability families — color fills, export profiles, asset browsing, parameter editing, and timelines.
4. Pivot and transform-order contracts — extend the shipped unit, origin, and axis conversion model to application-specific pivot behavior.
5. Adapter registry and conformance badges — distributable third-party manifests, version ranges, and reproducible compatibility evidence.
6. Accessibility and keyboard workflows — shared interaction research rather than merely copying existing application controls.
7. Guarded natural-language planning — an optional planner that proposes visible protocol operations, validates them, and requires confirmation. Arbitrary generated scripts and silent execution are explicitly out of scope.

Roadmap proposals belong in GitHub Discussions before implementation so the shared model does not grow by accident.

Testing

python -m pip install -e ".[dev]"
ruff format --check .
ruff check .
mypy src tests
pytest
npm test
npm run check
npm run build
python -m build

The ordinary suite tests schema rejection, transactions and rollback, resume drift, policies, pipelines, signatures, coordinate conversion, semantic diffs, adapter conformance, generated Blender/GIMP scripts, SVG semantics, CLI behavior, and the plan-builder core. GitHub CI also runs native Blender and Inkscape smoke tests on Ubuntu. GIMP native conformance is available through ccb conformance gimp --native on systems with GIMP 3 installed.

Privacy and platforms

CCB runs locally on Windows, macOS, and Linux wherever Python and the selected application are available. The static plan builder runs in modern browsers and does not transmit or store content.

Contributing and maintenance

Contributions are welcome through reviewed pull requests. Start with CONTRIBUTING.md, the development guide, and the adapter contract. Compatibility reports should include the operating system, application version, plan, expected semantic result, and actual result using synthetic fixtures where possible.

Version 1.3.1 is feature-complete for its documented scope. Maintenance prioritizes transaction safety, compatibility evidence, explicit policy, and backward-compatible protocol changes over rapidly adding application-specific commands.

License

MIT © 2026 Logan Pendragon Multiverse.

More open-source projects

This project is part of the Logan Pendragon Forge open-source collection. Browse the catalog for other released tools, source repositories, live demos, and downloads.

Version 1.4.0: reviewed improvements

Add portable font mappings with missing-font diagnostics, transform/pivot fixture generation and version-scoped conformance evidence.

The fonts command maps requested families per adapter, reports missing/unmapped families, accepts an optional operator-supplied family inventory, and writes a new resolved plan only when no blocking findings remain. Blender mappings use validated local TTF/OTF files through font_file and actually load the font; file presence alone is not a rendering claim. The fixture generator writes 12 transform cases plus 12 round-trip plans with explicit adapter-specific pivot semantics. conformance-matrix records exact observed application versions, separates contract-only/native-smoke/document-adapter evidence, and verifies Blender transform round-trips when available. CI requires real Blender transforms/font loading and Inkscape rendering, then uploads the measured version matrix. GIMP native semantic acceptance remains unverified when unavailable. Sources are preserved and existing output files are refused.

ccb fonts plan.json --map font-map.json --inventory installed-families.json --output mapped-plan.json
ccb conformance-fixtures new-fixtures
ccb conformance-matrix --native --output new-version-matrix.json

Version 1.5.0: reviewed improvements

Add read-only execution preflight and value-free semantic comparisons between two plans. The reference builder imports validated local JSON plans, retains coordinate metadata, reviews target order, edits/reorders/removes queued operations, and offers bounded session Undo/Redo. Existing output refusal, transactional execution, protocol version 1, and native adapter behavior are retained.

ccb preflight plan.json
ccb preflight plan.json --inspect --policy policy.json --receipt new-receipt.json
ccb compare-plans before.json after.json --output new-comparison.json

Preflight does not execute or reserve paths. Without --inspect, existing-document targets are not verified. Native inspection can launch the selected application in read-only mode. Signed-bundle requirements remain blocked in preflight; verify the bundle through the existing execution workflow. A blocked preflight or changed comparison exits 1; invalid input exits 2. Report destinations must be new files. Comparisons match explicit IDs, or position for operations without IDs; identifiers and field names still appear and should be reviewed before sharing.

The builder imports a local plan up to 1 MiB, validates before replacing the queue, and keeps Undo/Redo in the current browser session only. Queue editing produces a JSON plan; it does not launch a creative application. Inspect the saved plan before execution.

PNG export (1.6.0)

A separate strict export job supports static SVG → PNG through Inkscape with read-only preflight, requested canvas dimensions, collision refusal and hash receipts. It rejects external resources, scripts, CSS and unsupported SVG constructs before native execution. See the export contract for the exact schema and limits. Existing document-plan protocol and native editable outputs remain unchanged.