Skip to content

Upgrade to Hedron 1.1

This guide starts with the current 1.1 migration boundary, then retains historical notes for older release trains. The published release is 1.1.2 on the 1.1.x line. Read Current release and support for the published PyPI status before changing an application requirement.

1.0 → 1.1

Hedron 1.1 extends the stable 1.x application model without changing the core page, view, and action authoring roles. Upgrade the coordinated packages together and review the new contracts only where the application needs them:

1.1 area What to review
Identity and resources Add presentation hooks where views need identity or resource context
Collections Normalize paginated responses with bounded page and cursor state
Navigation Use request-aware navigation decisions for links, redirects, and prefetch
Secure forms Use write-only secret fields and explicit keep, replace, or clear operations
Application builds Adopt the application-aware build contract for reproducible release artifacts
Presentation Review native shell refinements and computed-style browser evidence

Upgrade the stable packages from PyPI:

python -m pip install -U "hedron>=1.1.2,<1.2" "edron>=1.1.2,<1.2"

Read What’s new in 1.1 and the 1.1.2 release notes for the complete feature and evidence boundary. Keep the application’s existing integration tests and add coverage for any newly adopted collection, navigation, or secure-form behavior.

Historical: 0.67 → 1.0

Hedron 1.0 is a subtractive, canonicalization release. Migrate the ordinary route surface to the three function roles below; each old spelling has a structured warning and a static finding.

0.67 path 1.0 path Notes
@app.screen @app.page Return one document tree; keep explicit Page when needed
@app.refreshable / @app.fragment @app.view View handlers return one tree and produce a view handle
@app.command / @app.form_command @app.action Unsafe requests default to POST and produce an action handle
app.include_feature(...) app.include(...) Feature ownership remains explicit
@router.component @router.view Advanced router integration; unsafe routes use @router.action

Run the non-executing check first, review the proposed diff, and only then write an output tree:

python -m hedron --app app:app check --target 1.0 --project .
python -m hedron migrate api --target 1.0 . --out migrated-app

The migrator is intentionally conservative: region-specific, dynamic, direct-import, and unsafe-component forms remain manual-review findings. It never imports the application, executes source, or overwrites an existing output. Run the checker again on the reviewed result and keep the original tree for rollback until the application passes its own 1.0 checks.

The canonical source fixture is exercised by the repository bridge:

python scripts/check_upgrade_100.py --baseline v0.67.0 --json

The bridge currently proves the baseline/current HTTP and HDJ probe only; it does not authorize publication while retained 1.0 artifacts and full release evidence are unavailable.

Historical release notes

The sections below document older upgrades and are not the 1.1 authoring path.

This guide covers upgrading an application to the stable 0.66.x train (v0.66.2) from PyPI or a source checkout. The v0.67.0 train is Beta preview. Public-index notes: Installation. New applications should use Build your first app.

0.58 → 0.62

The 1.0.x checkout tip uses uv sync. See What's new in 0.62, Hedron API, and Presentation.

  1. Upgrade the application pin to hedron>=1.0.0.
  2. Keep existing viewport responsive maps unchanged; opt into component-width behavior with Container(query="inline-size") and add name= only for nested query targeting.
  3. Use StyleScope(variant=...) for explicit theme variants and retain the default theme marker for existing pages.
  4. Replace app-owned button sizing/forwarding selectors with Button / LinkButton size, width, and validated attrs.
  5. Run the compiler, browser, consumer, performance, and package checks after the upgrade.

0.57 → 0.58

The 1.0.x checkout tip uses uv sync. From the public index, install hedron>=1.0.0. See What's new in 0.58, Hedron API, and Presentation.

  1. Upgrade the application pin to hedron>=1.0.0.
  2. Prefer progressive facades for new golden paths: @app.page, @app.view, and @app.action, DataWorkspace.with_screen, TaskFlow, DashboardWorkspace, SessionAuthFlow, UploadFlow, plus DesignSystem / StyleRecipe / StyleScope where styling applies.
  3. Keep labeled Advanced @app.page / explicit handle spellings when graduating or ejecting; Flask/Django hosts remain Supported but are not decorator-parity Supported for these facades.
  4. Use hedron explain / hedron style for static redacted inspection of features and designs.

0.56 → 0.57

The 1.0.x checkout tip uses uv sync. From PyPI, install hedron>=1.0.0. See What's new in 0.57 and Presentation.

  1. Upgrade the application pin to hedron>=1.0.0.
  2. Prefer named gap tokens (sm/md/lg) over ambiguous CSS lengths.
  3. Adopt Surface / chrome / ResourceList presentation markers instead of application CSS.

0.55 → 0.56

The 1.0.x checkout tip uses uv sync. From PyPI, install hedron>=1.0.0. See What's new in 0.56 and Security control plane.

  1. Upgrade the application pin to hedron>=1.0.0.
  2. Adopt SecurityPolicy presets and hedron security-check for posture baselines.
  3. Prefer shared egress / sensitivity / intent helpers over package-local copies.

0.52 → 0.53

The published v0.64.0 train supersedes the older 0.52/0.53 pins. Keep hedron>=1.0.0. See What's new in 0.53 and Application DX API.

  1. Application DX Stage 1 (RFC-0080 / D-091 / D-092). Prefer Stage 1 symbols (ApplicationAssetSpec / compile_application_asset_plan, ApplicabilityInterval / RemediationAction / normalize_severity_alias, export_routes_document / export_effect_graph, OperationWorkflow / is_terminal_job_state, generate_interaction_tests, run_visual_conformance, discover_public_api, diagnose_installed_fleet) over ad-hoc forks of the shipped 0.52 seams.
  2. 0.52 conformance and Posit contracts remain. No rollback is required for apps upgrading from those historical pins.
# From the published PyPI train:
python -m pip install -U "hedron>=1.0.0"
# In-tree / source checkout tip:
# python -m pip install -U "hedron>=1.0.0"

0.51 → 0.52

Require hedron>=1.0.0 from PyPI (v0.52.0 LANDED). See What's new in 0.52.

  1. Conformance authority (RFC-0079 / D-089 / D-090). hedron-conformance is the portable-subset authority extending hedron-portable-1. Node/Java evaluators are independently installable reference consumers — not full Hedron ports.
  2. Posit lifecycle (#508–#513). Prefer CookieRegistry, PositContext / posit_for(request), opt-in hands_off, and hedron-posit check --matrix over app-owned cookie path math and redirect adaptation.
  3. 0.51 extras contracts remain. No rollback required for apps that never adopted Posit lifecycle helpers; add them when deploying under Workbench/Connect mounts.
python -m pip install -U "hedron>=1.0.0"

0.50 → 0.51

Require hedron>=1.0.0 from PyPI (or the in-tree 0.53 tip when developing Hedron itself). See What's new in 0.51.

  1. Curated extras depth (RFC-0078 / D-087 / D-088). ExtrasFeature is the hedron-extras inventory authority; shared extras HTMX hosts reconnect after swaps. JSON/Data/Chart workbenches stay cancelable and revision-aware.
  2. Sandbox stays opt-in. Default plugin registration requires hedron_extras_sandbox / HEDRON_EXTRAS_SANDBOX=1; BrowserPythonSandbox stays Experimental.
  3. Companion flagship authoring (#504–#506). Password show/hide, opt-in SwapReveal, and generic HTMX busy via BusyRegion / Hx(busy=...).
  4. 0.50 Explorer and HTMX contracts remain. No rollback required for apps that never adopted hedron[extras]; add the extra when you want the new widgets.
python -m pip install -U "hedron>=1.0.0"
python -m pip install -U "hedron[extras]>=1.0.0"

Summary

Hedron 0.64.x ships responsive navigation, bounded optimism, and localized failure isolation on top of the progressive feature and styling authoring train. Install hedron>=1.0.0 from PyPI.

Hedron 0.60.x shipped progressive feature and styling authoring on top of the 0.57 presentation train. Install hedron>=1.0.0 from PyPI.

  • Screens, form commands, workspaces, TaskFlow, DashboardWorkspace, SessionAuthFlow, UploadFlow, DesignSystem / StyleRecipe / StyleScope, explain/style CLI (Hedron API · Presentation)

Hedron 0.57.x ships unified presentation / zero-application-CSS on top of the 0.56 security control plane.

  • Shared appearance vocabulary, Surface/chrome/ResourceList, zero-app-CSS evidence (Presentation)

Hedron 0.53.x tip ships Application DX Stage 1 contracts on top of the 0.52 conformance/Posit train. From PyPI, keep using hedron>=1.0.0 until the 0.53 wheel lands.

  • Application assets, diagnostics, routes, workflows, testgen, theming, discovery, and fleet doctor (Application DX API)

Hedron 0.52.x ships cross-language conformance authority and Posit lifecycle companions on top of the 0.51 extras train (v0.52.0 on PyPI).

  • Portable-subset conformance authority + Node/Java evaluators
  • CookieRegistry, PositContext, hands_off, matrix check, diagnostics (#508–#513)

Hedron 0.51.x ships curated extras and companion HTMX authoring on top of the 0.50 Explorer architecture cut:

  • ExtrasFeature, shared extras HTMX lifecycle, workbench/image/input depth, sandbox opt-in
  • Accessible password toggle, swap reveal, and generic HTMX busy (#504–#506)

Hedron 0.50.x ships Explorer architecture and companion HTMX authoring on top of the 0.49 FastAPI/Pydantic convergence:

  • Thin explorer_router, ExplorerProvider isolation, cursor pagination, catalog diffs, and CLI/HTML/JSON agreement when hedron-explorer is installed
  • Production still force-offs explorer="development" after RISK_EXPLORER_DEVELOPMENT (accept the risk, Explorer still does not mount)
  • ActionHandle.effect / after(load=), Lazy error templates, Select.depends_on, and danger Toast dismiss compile to HTMX
  • 0.49 handle, TypeSchema, and catalog contracts remain:

Hedron 0.49.x compiles existing handle, TypeSchema, and catalog plans onto FastAPI:

  • DependsOn / DependencyLifetime compile to FastAPI Depends(scope="function"|"request")
  • BoundaryBindingPlan chooses native-model or expanded-fields; BindingPlan stays URL identity
  • Additive TypeSchema v2 input/output projections; v1 readers remain
  • Tagged public-wire kind unions and cached TypeAdapter on non-FormBody candidates
  • Router provenance, OpenAPI projection, and non-granting RequiresScopes
  • Workbench/Posit keep custom loaders. FailFast / Pydantic MISSING stay research-only

0.48 HTMX extensions remain:

  • Closed Page.htmx_extensions / HtmxExtension / ExtensionSet with demand-driven pinned local sse, head-support, and preload assets
  • Unset pages keep the 0.47 sse + head-support compatibility default; htmx_extensions=() loads zero extension bytes
  • SseRegion / SseTrigger over experimental SSE helpers; polling remains the Supported fallback
  • Idiomorph / morph swap is Deferred and is not a Supported capability

Maps from 0.47 remain:

  • MapSpec / MapPlan / compile_map compile a closed, redacted map grammar
  • hedron_maps.Map defaults to attributed OpenStreetMap.standard(); core hedron.Map is unchanged
  • Custom XYZ / TileJSON / vector sources, static images, PMTiles, bounded MBTiles, and blank maps
  • Pinned strict-CSP MapLibre behind hedron-map; MapInteraction binds declared events
  • Semantic table alternatives survive no JavaScript / WebGL / CSP / network failure

Apps that never install hedron-maps stay request-path identical to 0.46. Direct hedron.Map and explicit chart map adapters remain. Prior trains remain in force: package-native workflows (0.46), interaction catalog (0.45), type-driven authoring (0.44), refreshable views and commands (0.43), production-grade Web Component inventory (0.42), browser composition / draft transfer / navigation (0.41), authoring kit (0.40), rich data / OptimisticMutation (0.39), high-fidelity charts (hedron-charts 0.2.x, 0.38), MCP (hedron-mcp 0.2.x), Workbench ASGI (fastapi-workbench 1.x), and Posit (hedron[posit] / HedronPosit). Polling remains the production recommendation for live status. SSE, WebSocket, streaming, and navigation preload remain experimental.

Before upgrading

  1. Commit or back up your lockfile.
  2. Confirm you are on a recent pin (hedron>=0.29.0,<0.30 through >=1.0.0, or the tip pin already). Public-index notes: Installation.
  3. Existing 0.42–0.46 handlers and unused include_feature keep working.
  4. Adopt maps only via hedron[maps] / from hedron_maps import ….
  5. If you use editable grids or charts, keep hedron[data] / hedron[charts] on the tip pin (or hedron-charts>=0.2.3,<0.3).
  6. If you use Posit Workbench or Connect, prefer hedron[posit] / HedronPosit.

Install

python -m pip install -U "hedron>=1.0.0"
python -m pip install -U "hedron[data]>=1.0.0"
python -m pip install -U "hedron[charts]>=1.0.0"
python -m pip install -U "hedron[maps]>=1.0.0"
# optional production-grade elements inventory:
python -m pip install -U "hedron[elements]>=1.0.0"

Public-index notes: Installation.

Behavioral notes (0.46 → 0.47)

  1. Core Map stays core. from hedron import Map does not gain an OSM default or MapLibre host.
  2. OSM default is hedron_maps.Map only. basemap=None is a blank map, not OSM.
  3. Charts map adapters stay explicit. MapLibre/Folium/PyDeck on hedron-charts do not silently switch to hedron-maps.
  4. Rollback: uninstall hedron-maps and revert hedron_maps imports; pin hedron>=0.46.0,<0.47 from the registry.
  5. Map origin policy. Custom OpenStreetMap(tile_url=...) and Map(tiles=) require exact-origin allowlists; empty prefixes fail closed.
  6. Generated list views page. DataWorkspace list routes honor offset / limit / sort / q and allowlisted field filters.
  7. MCP authorize isolation. Pin hedron-mcp>=0.2.4,<0.3 with coordinated 1.0 artifacts (or use the public hedron[mcp]>=1.0.0 pin) so a second McpExposure.apply cannot overwrite the first tool's authorize hook.

Behavioral notes (0.45 → 0.46)

Hedron 0.46.x added opt-in package-native features that compile onto existing 0.43–0.45 seams:

  • FeatureBundle / Hedron.include_feature atomically register ordinary handles, components, scenarios, and stacked projections; they are not executors
  • DataWorkspace produces a beginner app.include(orders) bundle over an explicit DataEditorSource and DataWorkspacePolicy
  • ChartInteraction maps Supported select / inspect / focus / reset onto ActionHandle effects; legend_filter / brush / drill_intent stay Experimental
  • Schema-aware elements are opt-in (ActionHandle.form(enhance="elements")); native forms remain canonical

  • McpExposure and RemoteWorkflow wrap live MCP/Gradio registration; catalog presence never grants exposure

  • Bundles are not executors. include_feature registers ordinary 0.43–0.45 handles, components, scenarios, and stacked projections. Authz stays explicit; catalog presence is not a capability.

  • Unused include is request-path identical. Apps that never call include_feature keep the 0.45 request path.
  • MCP/Gradio stay opt-in. McpExposure / RemoteWorkflow wrap live registration; consuming the catalog never grants exposure.
  • Rollback: pin hedron>=0.45.0,<0.46. Eject or remove include_feature first; explicit handlers stay.

Behavioral notes (0.44 → 0.45)

  1. Catalog is not authority. Routes, validation, authorization, and execution still come from 0.43 descriptors and optional 0.44 TypeSchema. Catalog ids/fingerprints are not capabilities.
  2. Unused catalog is request-path neutral. Apps that never inspect app.interactions keep the 0.44 request path.
  3. Production interactions.json is required only when the live sealed catalog has entries.
  4. Rollback: pin hedron>=0.44.0,<0.45. Remove catalog consumers first; handlers stay.

Behavioral notes (0.43 → 0.44)

  1. Opt-in only. Unmodeled handlers keep structural bind, explicit forms, and dynamic/observed effects. schema stays None until a Hedron marker is present.
  2. One compiled validator. bind(model) and bind(**fields) share the Pydantic adapter. A bare BaseModel argument is not inferred as a boundary.
  3. Forms are inventory-backed. ActionHandle.form() exists only for a supported FormBody. Nested models, unions, and lists of models need explicit Form overrides.
  4. Declared effects do not execute. Actual refresh() / PatchSet targets must be a subset of declared same-app handles.
  5. Rollback: pin hedron>=0.43.0,<0.44. Generated form ids follow the 0.43 handle ids.

Behavioral notes (0.42 → 0.43)

  1. This historical 0.43 note predates the 1.0 boundary. In 1.0, @app.view and @app.action are canonical handle-producing decorators; use the 0.67 → 1.0 section above for migration.
  2. Refresh is not a full page reload. Top-level refresh() compiles to bounded HX-Trigger events; it does not set HX-Refresh.
  3. Generated ids are not rollback-stable. Explicit path= / key= are the compatibility hatches. Rollback: pin hedron>=0.42.0,<0.43.
  4. Mixed refresh + patch in one return fails closed. Toast + refresh is allowed.

After upgrading

  • Keep existing pages and 0.46 map-free routes running unchanged, then add one hedron_maps.Map at a time.
  • Smoke OSM, custom XYZ, and one offline path (static image or blank map) with and without JavaScript.
  • Confirm Explorer /hedron-explorer/maps and hedron inspect without treating catalog presence as exposure.

See also