Files
Chronos/docs/plans/or1-phase-4.md
T
Alby96andClaude Opus 5.5 188b2c2e55
CI / Build and test (push) Successful in 8m19s
CI / Windows tests and installer (push) Skipped
CI / YAML check (push) Successful in 7s
Release / Build, test and publish (push) Successful in 12m9s
CI / PostgreSQL 16 integration (push) Successful in 7m49s
CI / PostgreSQL 17 integration (push) Successful in 7m19s
CI / Docker image (push) Successful in 46s
Release / Server image (push) Successful in 1m14s
feat(editor): visual crop, rotate/mirror/flip/straighten, colour looks (owner review 1 phase 4) (#26)
Owner review 1 R5 + R6. Camera rotation, mirror, flip, straighten and crop handles locked to the output; an Exposure Look group; Export output size ("proportions win"); settings format 2 with older-node gates. Also fixes project text and hashes differing between Windows and Linux.

Closes #19
Closes #20

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Alberto Balbo <alberto.balbo.96@gmail.com>
2026-11-05 01:09:09 +01:00

47 KiB
Raw Blame History

Owner review 1, phase 4: visual crop (R5) and simple filters (R6), final plan

Context

Owner request. This is docs/requests/2026-10-15-owner-review-1.md, row 4.

  • R5, visual crop. The user moves and resizes the crop mask on the preview, locked to the chosen proportions. The owner's Q&A answer: "the chosen proportions win; the preset adapts its resolution (4K at 9:16 = 2160×3840)".
  • R6, simple filters. Mirror, flip, 90° rotations, a free-angle straighten, and colour filters.
  • Owner review 2. These become project settings: versioned per project, portable, merged field by field, kept by older clients through [JsonExtensionData]. A project in a newer settingsFormat opens read-only.

What exists today (checked in src/Chronos.Core/Project/ProjectSettings.cs:165-293):

  • CameraSettings holds Crop (a double[]? of normalised [x,y,w,h]), Aspect (an Auto<string>), OffsetX/OffsetY, Keyframes and Extra.
  • CurrentVersion = 1 and Version defaults to CurrentVersion. A version above CurrentVersion opens read-only.
  • A fixed-size preset wins over the camera aspect, with the warning Export.Render.AspectFromPreset (RenderGeometry.cs:88-91). This is the opposite of R5.
  • The crop mask in the preview is display-only (PreviewSurface.DrawCropMask). The crop is edited through four margin sliders (CropMargins.cs).
  • There are no orientation, straighten or colour-filter settings. The knee is applied by hand in both RenderPipeline.EmitAsync:413 and PreviewRenderer.cs:285.

Choice of base. Design A is the base. It has one Core source of truth for every pixel decision:

  • a shared FrameFinish (colour, then knee) that the render, the preview, the server and the nodes all call;
  • RenderSize as a pure function the server routing uses;
  • a routing format rule that also catches "proportions win" jobs;
  • push and render gated on the desktop against older servers;
  • contracts and self-test partials created in P0, so the parallel packages do not collide.

These parts come from Design B:

  • a minimal colour scope: a named look plus its strength, in a root look section;
  • the derived rows Crop size, Crop X and Crop Y in place of reusing the offset keys;
  • a ±15° straighten;
  • Version defaulting to the literal 1;
  • the advisor aspect worked out on the oriented frame;
  • ViewToFrame for mapping overlays;
  • Esc to cancel and Alt to resize about the centre;
  • Reset framing.

These parts of A stay: the stored members Rotate, Mirror and Flip mirror what the user sees, the crop is refitted when the aspect changes, and the colour runs before the knee.

Two facts checked for the packaging:

  • i18n check reports a key removed from en as an orphan in all 38 locales. Unused English keys are not flagged. So keys are removed only once, in P6, with i18n prune.
  • Job errors already go through Loc.L("Errors.Render.*") (RenderJobHandler.cs:42).

Decisions to record (docs/DECISIONS.md rows, added in P0)

  1. Conditional settings format.
    • CurrentVersion = 2 means "the highest format this build reads".
    • ToJson writes the lowest format that renders the same: 2 only when a turn, mirror, flip, straighten or non-identity look is set, otherwise 1.
    • ProjectContent.FormatOf falls back to the literal 1.
    • Effect: every project that does not use these features keeps byte-identical canonical text and hash, and older builds treat it as before.
  2. General rule for future members. A member that changes pixels and that the previous format would ignore raises the written format only when it is used. It is declared after the existing members and omitted at its default. Lists that grow are strings, not enums.
  3. Orientation members and order.
    • rotate holds 0, 90, 180 or 270 degrees clockwise, applied after Exif orientation.
    • Then mirror (left↔right) and flip (top↔bottom), in screen axes after the turn.
    • Then straighten, ±15°, positive clockwise.
    • All of this sits inside the single warp, between the stabilisation and the virtual camera. Pixels are never rotated after decode, so the stabiliser paths, the sky mask and the horizon stay in raw-frame space.
  4. Straighten cover zoom. The zoom is automatic and never stored: c = cos|θ| + max(W'/H', H'/W')·sin|θ|. No clamped (smeared) border can ever show, and any crop in [0,1]² stays valid.
  5. Crop coordinates.
    • camera.crop and the keyframe centres are normalised in the view frame T: oriented, straightened and cover-zoomed. With the identity transform that is exactly today's meaning.
    • The crop stays an atomic array in ProjectMerge. A concurrent move and resize therefore give one camera.crop conflict, never a rectangle of the wrong ratio.
  6. Locked crop.
    • Editor edits write the aspect-locked box itself and set offsetX/offsetY to 0. FitCrop then returns the box unchanged.
    • The first edit of a legacy free crop with offsets bakes them in: FitCrop(crop, ratio, offsets).
    • The renderer keeps FitCrop as the safety net for merged or hand-edited pairs.
    • An aspect change refits the box: same centre, the new ratio, kept inside the frame.
  7. A quarter turn keeps the content.
    • Rotate left/right remaps the crop and the keyframe centres exactly, and transposes a non-square aspect (manual value, or the Auto's advised value): 16:9 becomes 9:16.
    • Mirror and flip remap the crop and centres and negate the keyframe roll.
    • Each press is one undo step.
  8. Proportions win.
    • When the resolved aspect is not "source", a fixed-size preset becomes a size box. The aspect is fitted inside the box, turned to portrait when the ratio is below 1. Results: 4K at 9:16 = 2160×3840, 1:1 = 2160×2160, 4:5 = 2160×2700, 21:9 = 3840×1646; 1080p at 9:16 = 1080×1920.
    • "source" keeps the preset's ratio, so default and unresolved projects do not change.
    • Sizes stay even for non-managed codecs. AspectFromPreset is removed. The preset name does not flip to Custom.
  9. Proportions win is not format-gated in storage. Raising the format for it would drift the canonical text of stored projects and spawn External versions (ProjectService.cs:685-690, 808-830). It is gated only in routing (row 10) and in the desktop's server gating (row 11). The output change is a CHANGELOG upgrade note.
  10. Routing format.
    • RenderRules.RequiredFormat(settings, resolvedExport, srcW, srcH) is the max of the settings' written format and 2 when the adapted size differs from the preset's fixed size. It is never written.
    • Nodes announce RegisterNodeRequest.SettingsFormat; an older node reads as 1.
    • Jobs carry RenderJobParameters.RequiredSettingsFormat.
    • A claim and the "awaits a node" check skip incompatible nodes.
  11. Server format announcement.
    • ServerInfo.SettingsFormat is new; null from an older server means 1.
    • The desktop disables Push and Send-and-render when the required format exceeds the server's, with a tooltip giving the reason (the pattern of the DECISIONS row at docs/DECISIONS.md:656).
  12. Colour (look).
    • The look is parametric and built in: no LUT files, which a server or Docker image would not have.
    • It is a linear-light 3×3 matrix, a contrast power about 0.18 and a lift, blended by strength.
    • It is applied once per output frame after stacking, interpolation and blur, and before the knee, so the knee compresses any overshoot.
    • It is never seen by measuring, flow or stacking.
    • look.filter is a string; an unknown name renders as identity with a warning.
  13. No ninth step. The transforms join the Camera step and the look joins the Exposure step (BRIEF §12.3). Alt+1…8, "n / 8" and the 82-px step cells are unchanged.
  14. Raw thumbnails. Library, filmstrip, hero and admin-panel covers stay raw photos.
  15. Preview Source framing.
    • With a non-identity transform, the whole T frame is shown, without stabilisation or camera pose. The Camera-step mask is then static and maps 1:1 to camera.crop.
    • The Export step shows the per-frame output footprint mapped into T.
  16. Global only. The new settings are not per-frame and not frame-keyed, so there are no new parked positions. The keyframe Rotation roll is unchanged.

Settings schema

All new members are declared after the existing ones and before Extra, and are omitted at their default. No new C# enums.

// CameraSettings (ProjectSettings.cs:165-180), after Keyframes, before Extra
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] public int Rotate { get; init; }        // 0/90/180/270
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] public bool Mirror { get; init; }
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] public bool Flip { get; init; }
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] public double Straighten { get; init; } // degrees, ±15
[JsonIgnore] public int Turns => ((Rotate / 90 % 4) + 4) % 4;   // valid only when Rotate % 90 == 0
[JsonIgnore] public bool IsOriented => Rotate % 360 != 0 || Mirror || Flip || Straighten != 0;

The render rules for these members:

  • Rotate is normalised modulo 360. A value that is not a multiple of 90 counts as 0, with the warning Export.Render.RotationIgnored.
  • Straighten is clamped to ±15, with Export.Render.StraightenClamped. A non-finite value counts as 0 with the same warning.

Doc comments to update:

  • Crop: "normalised [x,y,w,h] of the view frame (oriented, straightened, cover-zoomed)".
  • Aspect: the output proportions; a fixed preset adapts its size to them.
// ProjectSettings, after PendingFrames (:275), before root Extra (:285)
public LookSettings? Look { get; init; }                         // "look", null => omitted

public sealed record LookSettings
{
    public string? Filter { get; init; }   // null|"none"|"mono"|"sepia"|"warm"|"cool"|"vivid"|"muted"|"fade"
    public double? Strength { get; init; } // 0..1, null = 1
    [JsonIgnore] public bool IsIdentity => Filter is null or "none" || Strength is <= 0;
    [JsonExtensionData] public Dictionary<string, JsonElement>? Extra { get; set; }
}
  • The editor writes Look = null whenever the look is the identity.
  • The name look avoids the test fixtures' unknown filters (ProjectContentTests.cs:309) and grade (ProjectMergeTests.cs:105).

Format (ProjectSettings.cs:249, 257, 295):

public const int CurrentVersion = 2;   // highest readable
public const int BaseVersion = 1;
public int Version { get; init; } = BaseVersion;
[JsonIgnore] public int RequiredFormat => Camera.IsOriented || Look is { IsIdentity: false } ? 2 : BaseVersion;
public string ToJson() => JsonSerializer.Serialize(IsNewerFormat ? this : this with { Version = RequiredFormat }, ProjectJson.Default.ProjectSettings);
  • ProjectContent.FormatOf (:239-253) falls back to ProjectSettings.BaseVersion.
  • P0 audits every direct use of ProjectJson.Default.ProjectSettings outside ToJson. Each one must go through ToJson, or a project with transforms would be written as v1.
  • ProjectMerge needs no code change. FromKeyed goes through FromJson/ToJson, so the merged version is recomputed. P0 tests pin this.
  • Unchanged: Protocol settings strings, the SQL, PATCH /sequences (IsJson only), SyncRules.NormalizeSettings, and ProjectBundle formats 1, 2 and 3. A v2 project in a format-1 file is refused by old builds, as intended.

Protocol (optional trailing members, compatible both ways):

  • ServerInfo(..., int? SettingsFormat = null) (Dtos.cs:16-24).
  • RegisterNodeRequest(..., int SettingsFormat = 1) (Jobs.cs:31).
  • RenderJobParameters(..., int RequiredSettingsFormat = 1) (Jobs.cs:62).

Pipeline order

The same order applies to the render, the server, the render nodes and the preview. Everything runs in Chronos.Core on the CPU, with one resample.

  1. Decode. Exif orientation is applied at decode, unchanged. This gives the raw frame R, W×H.

  2. RGB, then exposure (deflicker, white balance, regions), in raw space (RenderPipeline.cs:367-368, unchanged).

  3. One warp (RenderGeometry.For, :133-147, then GeometryStage.Apply): Warp = stab⁻¹ · O⁻¹ · V.

    • O = FrameOrientation.Of(camera, W, H), new in src/Chronos.Core/Imaging/Geometry/FrameOrientation.cs, equal to S_straighten · F_mirror/flip · Q_turn. It maps the stabilised raw frame to the view T, of size W'×H' (swapped for odd turns).
      • Q and F are exact integer matrices in GeometryStage's pixel-centre convention. Affine2D.Rotation(π/2) must not be used, because its cosine is about 6e-17.
      • S is Affine2D.About(Similarity(1/c, θ)) about the centre of T.
    • V = VirtualCamera.ViewToSource(pose, W', H'): keyframe centres in T, plus the stabilisation zoom.
    • The crop is camera.crop × (W', H'), followed by FitCrop(ratio, offsets).
    • maxZoom = keyframe zoom × stabilisation zoom × c. It feeds WorkingLongEdge (:61-70, :113). Turns do not change the long edge.
  4. Output size: RenderSize.Of(camera, export, srcW, srcH), new in src/Chronos.Core/Render/RenderSize.cs. It replaces RenderGeometry.cs:88-103:

    Case Output size
    Fixed preset, aspect not "source" Adapt(box, r)
    Fixed preset, "source" The preset size
    One side given The other side derived from r
    No side given The fitted crop

    Sizes are made even for non-managed codecs. After that, EncoderSelector.Fit caps the size as today.

  5. Prepared cache, then flow, interpolation, motion blur and stacking, all unchanged at output size.

  6. EmitAsync (:413): FrameFinish.Apply(frame, look, knee), new in src/Chronos.Core/Render/FrameFinish.cs.

    • First LookFilter.Apply (new, src/Chronos.Core/Imaging/Color/LookFilter.cs): linear light, no clamping, Vector<float>, parallel chunks like ExposureProcessor.
    • Then the knee, then the encoder.
  7. Measuring pass. RenderPreparation is unchanged: it never sees the transforms or the look.

Preview (src/Chronos.App/Editor/PreviewRenderer.cs):

  • Geometry() (:250-260) keeps calling RenderGeometry.Create, so size, ratio, orientation and cover zoom match the render.
  • Output framing uses the render's For() warp.
  • Source framing:
    • With !camera.IsOriented, the picture is the unwarped frame, at today's cost.
    • Otherwise both corrected and original are warped with RenderGeometry.ViewFor(frameW, frameH, outW, outH): the whole T frame, without crop, pose or stabilisation, at the preview long edge.
    • The horizon polyline and the region mask are mapped through RenderGeometry.ViewToFrame(...)⁻¹.
  • Mask rectangle:
    • Camera step: RenderGeometry.EditableCrop(camera), which is FitCrop in T, normalised and the same on every frame.
    • Export step: RenderGeometry.FootprintInView(plan), which replaces CropOf (:348-360).
  • The knee line (:285) becomes FrameFinish.Apply on corrected only, so the compare wipe shows before and after.
  • The corrections key (:170-175) is unchanged: the look is not inside Exposure, so moving its sliders never triggers a re-measure.

UI

Edit path

The path keeps its 8 steps. The transforms and the crop go in Camera and the look goes in Exposure.

  • EditPath.HasHandValues (:197-204):
    • Camera counts Crop != null, the offsets, the keyframes and IsOriented.
    • Exposure adds Look != null.
  • Signature already marks renders outdated.
  • EditorSession.ApplyPreset (:153-165) keeps the camera members and Look.

Camera step rows

In CameraTab.cs and EditorPanels.xaml:215-253, top to bottom:

  1. Aspect: the existing AutoChoiceRow. A change refits the crop (CropFrame.Refit).
  2. Rotation: two IconButtons, Rotate left and Rotate right, plus the value text "{0}°". This needs a new IconActionsRow in SettingRows.cs.
    • The buttons go through EditorSession.Orient(op), which calls Core OrientationEdit.
    • The turn direction is inverted when mirror xor flip is set, so the press turns the picture as the user sees it.
  3. Mirror and Flip: switch rows. This needs a new plain SwitchRow using the CheckBox.Switch template. Each toggle is one Orient op.
  4. Straighten: a NumberRow from −15 to 15°, step 0.1, merge key = header. While the slider is dragged or focused, the preview shows a fine 8×8 grid.
  5. Crop size: a NumberRow from 10 to 100 % of the largest locked box.
  6. Crop X and Crop Y: NumberRows from −1 to 1, the centre of the box within the frame's slack. They read and write Crop through CropFrame and set the offsets to 0.
  7. The keyframe group, unchanged.
  8. Reset framing: a button next to Optimise/Reset.
    • It clears the crop, the offsets, rotate, mirror, flip and straighten. It never touches the keyframes.
    • It is enabled only when one of them is set.

The four crop-margin rows, the Offset X/Y rows and CropMargins.cs are removed. The render still honours legacy offsets.

Exposure step

A "Look" group at the end of ExposureTab.cs:

  • Filter: a ChoiceRow with None, Mono, Sepia, Warm, Cool, Vivid, Muted and Fade.
  • Strength: 0–100 %. It is disabled and shows "n/a" when the filter is None.
  • Reset section keeps resetting only the Auto values.

Export step

In ExportTab.cs and ExportPlanner.cs:

  • Width and Height edit the preset box. They now load the resolved box (:496-498), not the encoder size.
  • A new InfoRow, Output size, shows RenderSize.Of, for example 2160 × 3840, with a capped mark when the encoder shrank it.
  • ExportPlanner estimates from the adapted size.

Crop overlay

In src/Chronos.Ui/Visuals/PreviewViewport.cs and PreviewSurface.cs:

  • Mask state. On the Camera step the mask is on by default, as a third per-step state beside _showCropMask and _exportCropMask (EditorViewModel.cs:65-67, 368-380).

  • When editing is allowed. CropEditable = Camera step && ShowCropMask && Editor.IsEditable, so not when the project is locked, read-only, in a newer format or busy.

  • New dependency properties: CropEditable, CropLockRatio (OutputRatio·H'/W', in normalised units), EditCrop (two-way draft), ShowGrid, and the routed event CropEditCompleted(Rect).

  • Drawing (DrawCropMask, :143-154):

    • the scrim and outline as today, with an Accent outline while editing;
    • 8 handles (4 corners and 4 edge midpoints), 8 screen px using unit = 1/scale, Card fill and Accent stroke;
    • rule-of-thirds lines while dragging;
    • the straighten grid when ShowGrid is on.
  • Hit-test priority (OnMouseLeftButtonDown, :245-262):

    1. a handle, within 6 screen px;
    2. the wipe divider;
    3. inside the box, which moves it;
    4. outside, which pans.

    Double-click keeps Fit/1:1.

  • Resize:

    • corner handles are anchored at the opposite corner;
    • edge handles are anchored at the opposite edge and stay centred on the other axis;
    • Alt resizes about the centre.
    • The ratio stays locked, the minimum is 10 % of the largest box, and the rect is clamped to [0,1]².
    • The math lives in Core CropFrame.
  • Cursors (OnQueryCursor, :303-312): SizeNWSE and SizeNESW on corners, SizeWE and SizeNS on edges, SizeAll inside.

  • Commit:

    • During a drag only the draft and the overlay change.
    • On mouse up or LostMouseCapture, CropEditCompleted fires. A new src/Chronos.App/Editor/CropCommit.cs, cloned from CurveCommit.cs, passes it to EditorViewModel.CommitCropCommand, which runs Session.Edit(..., "Camera.Crop"). One drag is one undo step.
    • Esc cancels the drag.
  • Keyboard (viewport focused): arrows move the box 1 %, Shift+arrows 10 %, and +/− resize it 2 % about the centre. P3 checks these against the existing viewport shortcuts. A run of key presses merges under "Camera.Crop", and the existing KeyUp EndEditRun (SequenceView.xaml.cs:23-27) closes the undo step.

  • Automation: the peer (:437-454) exposes the value "x 12 %, y 5 %, size 80 %".

  • Lint: XamlLintCommand (:11-15) adds PreviewViewport to the actionable controls.

Icons

Add RotateLeft, RotateRight, Mirror, Flip and Straighten in branding/ui-icons/icons.py, which writes src/Chronos.Ui/Icons/Icons.xaml and the admin icons.js. They are not mirrored in right-to-left languages.

String keys (en / it; labels ≤ 3 words; every control has a tooltip)

Labels:

Key en it
Editor.Camera.Rotation Rotation Rotazione
Editor.Camera.RotateLeft Rotate left Ruota a sinistra
Editor.Camera.RotateRight Rotate right Ruota a destra
Editor.Camera.Mirror Mirror Specchia
Editor.Camera.Flip Flip Capovolgi
Editor.Camera.Straighten Straighten Raddrizza
Editor.Camera.CropSize Crop size Dimensione ritaglio
Editor.Camera.CropX / CropY Crop X / Crop Y Ritaglio X / Ritaglio Y
Editor.Camera.ResetFraming Reset framing Ripristina inquadratura
Editor.Look.Group Look Aspetto
Editor.Look.Filter Filter Filtro
Editor.Look.Strength Strength Intensità
Editor.Look.None/Mono/Sepia/Warm/Cool/Vivid/Muted/Fade None/Mono/Sepia/Warm/Cool/Vivid/Muted/Fade Nessuno/Mono/Seppia/Caldo/Freddo/Vivace/Tenue/Sbiadito
Editor.Export.OutputSize Output size Dimensione uscita
Editor.Value.Degrees (only if not already present) {0}° {0}°

Tooltips (Tooltips.resx):

  • New, for the Camera step:
    • Tooltips.Editor.Camera.RotateLeft: "Turns the picture a quarter turn anticlockwise".
    • Tooltips.Editor.Camera.RotateRight: "Turns the picture a quarter turn clockwise".
    • Tooltips.Editor.Camera.Mirror: "Swaps left and right".
    • Tooltips.Editor.Camera.Flip: "Turns the picture upside down".
    • Tooltips.Editor.Camera.Straighten: "Levels the horizon; the picture zooms in just enough to hide the corners".
    • Tooltips.Editor.Camera.CropSize, CropX, CropY and ResetFraming: not drafted yet.
  • New, elsewhere:
    • Tooltips.Editor.Preview.CropEdit: "Drag to move · drag a handle to resize, aspect kept · arrows nudge".
    • Tooltips.Editor.Look.Filter and Tooltips.Editor.Look.Strength: not drafted yet.
    • Tooltips.Editor.Export.OutputSize: "The preset's resolution fitted to the chosen aspect".
    • Tooltips.Server.NeedsNewerServer: "This server's Chronos cannot read these settings; update it".
  • Reworded:
    • Tooltips.Editor.Camera.Aspect (:139): "Output proportions; a preset's resolution adapts to them (4K at 9:16 = 2160×3840)".
    • The Width and Height tooltips on the Export step.

Other areas:

  • Export.resx: Export.Render.RotationIgnored, Export.Render.StraightenClamped, Export.Render.LookIgnored.
  • Errors.resx: Errors.Render.NewerSettings "These settings need a newer Chronos".
  • Server.resx: Server.Setting.Rotation, .Mirror, .Flip, .Straighten, .LookFilter, .LookStrength. SyncText.SettingKeys maps them to camera.rotate, camera.mirror, camera.flip, camera.straighten, look.filter and look.strength.

Removed in P6 with i18n prune across all 38 locales:

  • Editor.Camera.CropLeft, CropTop, CropRight, CropBottom;
  • Editor.Camera.OffsetX, OffsetY and their tooltips;
  • Tooltips.Editor.Camera.Crop;
  • Export.Render.AspectFromPreset.

The Server.Setting.* labels for offsets stay.


Server and compatibility

The server needs no pixel code and no settings validation. PATCH and push stay opaque, and the admin panel stays read-only.

  1. Job sizes.
    • ProcessingJobs.Parameters and Split (src/Chronos.Data/Processing/ProcessingJobs.cs:87-136) compute the size with RenderSize.Of and write RequiredSettingsFormat = RenderRules.RequiredFormat(...).
    • JobEndpoints.CreateAsync (src/Chronos.Server/Api/JobEndpoints.cs:99-119) resolves the settings the job will render before Split: the embedded settings, else the version through ProjectRenderAsync, else sequence.SettingsJson read with FromJson(allowNewer:true). Text it cannot read keeps the preset size.
    • SourceSizeAsync stays the Exif-oriented size, because RenderSize.Of applies the turn.
  2. Nodes.
    • RenderNodeClient.RegisterAsync (:118-125) sends SettingsFormat = CurrentVersion. The value is stored inside the capabilities JSON, so no migration is needed.
    • RenderNodeService.ClaimAsync (:80-120) calls SettingsAsync before TryClaimAsync. It skips a job when the format it requires (recomputed, at least the hint) is above the node's format, or when CanEncode fails on the adapted size.
    • RenderNodeAvailability.AwaitsNodeAsync (:23-38) applies the same format test, through the hint, so the managed fallback starts instead of waiting.
  3. Managed fallback.
    • ManagedRenderJobHandler.Produces (:86-87) checks the adapted size.
    • RenderJobHandler (:50-55) and ProjectStore.Parse (:26-37) turn an over-format InvalidDataException into Loc.L("Errors.Render.NewerSettings").
    • ProjectStore.UpdateLockedAsync (:52-71) never raises a v1 project, because ToJson stamps the version. A test pins this.
  4. Announcement and desktop gating.
    • SystemEndpoints.cs:41-49 sets ServerInfo.SettingsFormat.
    • The desktop reads it, with null meaning 1. src/Chronos.App/Editor/ServerJobs.cs (Send and render) and src/Chronos.App/Workspace/ProjectMenuViewModel.cs (push to a server home) disable the action with Tooltips.Server.NeedsNewerServer when the required format is above the server's: FormatOf(portable) for a push, RenderRules.RequiredFormat for a render.
  5. Encoder limits.
    • EncoderSelector.Fit (src/Chronos.Core/Export/EncoderSelector.cs:189-222) and CanEncode are checked against a real portrait encode on the dev PC: H.264 2160×3840 on Media Foundation, software and hardware (MediaFoundationEncoderProvider.cs:16).
    • If the limits turn out to depend on orientation, they become long-edge × short-edge in both places.

Compatibility matrix (goes in DECISIONS and the CHANGELOG):

Pairing v1 project v2 project Proportions-win job (v1)
New server, old node Rendered by the node Never sent to it Never sent to it
Old server, new desktop Works Push and render disabled, with a reason Render disabled, with a reason; push works
New server, old desktop Works Listed, opened read-only, never mirrored or merged The old desktop's own render uses the preset ratio (known limitation)
Old desktop, local — Read-only; a format-1 .chronos refuses it Renders at the preset ratio (CHANGELOG note)

Packages

Merge order:

  1. P0 first, alone.
  2. P1, P2, P5 and P7 (draft) in parallel.
  3. P3 and P4 in parallel, rebased on P1 and P2 before their parity tests.
  4. P6.
  5. P7 merged last.

Each package works in its own worktree. Another process may be running CI on the current branch.

P0: Groundwork (contracts, schema, format, protocol, strings, icons, fixtures, decisions)

Files:

  • Settings and format:
    • src/Chronos.Core/Project/ProjectSettings.cs: the members above, LookSettings, CurrentVersion/BaseVersion/RequiredFormat, ToJson stamping, and a doc comment holding the rules for future members.
    • src/Chronos.Core/Project/ProjectContent.cs: the FormatOf fallback becomes BaseVersion.
    • The audit: rg "ProjectJson.Default.ProjectSettings" src. Every path goes through ToJson.
  • New Core API:
    • src/Chronos.Core/Render/RenderSize.cs: Of and Adapt, fully implemented.
    • src/Chronos.Core/Render/RenderRules.cs: RequiredFormat, implemented.
    • src/Chronos.Core/Render/FrameFinish.cs: the knee implemented, calling LookFilter.
    • src/Chronos.Core/Imaging/Color/LookFilter.cs: Names, IsKnown, and an identity Apply stub.
    • src/Chronos.Core/Imaging/Geometry/FrameOrientation.cs, CropFrame.cs and OrientationEdit.cs: signatures with identity or simple clamp bodies.
  • One-line wiring:
    • src/Chronos.Core/Render/RenderGeometry.cs: new members ViewWidth/ViewHeight, OutputRatio, LockRatio, ViewFor, ViewToFrame, EditableCrop and FootprintInView, all with bodies equivalent to today. No behaviour change.
    • src/Chronos.Core/Render/RenderPipeline.cs, :413: FrameFinish.Apply.
    • src/Chronos.App/Editor/PreviewRenderer.cs, :285: FrameFinish.Apply.
  • Self-test: src/Chronos.Core/Render/Diagnostics/SelfTest.cs gets GeometryChecks() and ColourChecks() in its list (:53), with new empty partials SelfTestGeometryChecks.cs and SelfTestColourChecks.cs.
  • Protocol: src/Chronos.Protocol/Dtos.cs and src/Chronos.Protocol/Jobs.cs, the trailing members.
  • App: src/Chronos.App/Server/SyncText.cs (SettingKeys) and src/Chronos.App/Editor/EditPath.cs (HasHandValues).
  • Strings: i18n/en and i18n/it for Editor, Tooltips, Export, Errors and Server: adds and rewordings only.
  • Icons: branding/ui-icons/icons.py, then the generated Icons.xaml and admin icons.js.
  • Test fixtures: "version": 2, used as "a newer Chronos", becomes 3 in:
    • tests/Chronos.Core.Tests/Project/ProjectContentTests.cs (:134, :332), ProjectBundleTests.cs;
    • tests/Chronos.Data.Tests/Projects/ProjectMergeTests.cs (:72/:104/:118), ProjectRecoveryTests.cs:330, ProjectHistoryTests.cs:120, ProjectStoreTests.cs:352;
    • tests/Chronos.Data.Tests/Workspaces/WorkspaceNewerFormatTests.cs (:37/:70), WorkspaceMergeTests.cs;
    • tests/Chronos.App.Tests/.../RemoteSequenceSourceTests.cs (:412/:447/:477/:492), WorkspaceMenuTests.cs:259.
  • New tests: tests/Chronos.Core.Tests/Project/ProjectSettingsTests.cs, tests/Chronos.Core.Tests/Render/RenderSizeTests.cs (new), RenderRulesTests.cs (new), and tests/Chronos.Data.Tests/Projects/ProjectMergeTests.cs.
  • Docs: docs/DECISIONS.md, the 16 rows above.

Depends on: nothing.

Tests (Core and Data, on Linux):

  • Canonical stability:
    • The canonical text and hash of the default project and of existing fixtures are byte-identical to before.
    • Old-build simulation: the new members read into Extra and are written back in the same order, with the same hash.
  • Round trips and format:
    • Every new member round-trips.
    • RequiredFormat is 1 without features, 2 with any of them, and back to 1 when they are removed.
    • "version": 3 is read-only and keeps its number through Canonical.
    • FormatOf of text without a version is 1.
  • RenderSize: the theory table: 4K at 9:16, 1:1, 4:5 and 21:9; 1080p at 9:16; the Vertical preset at 16:9 gives 1920×1080; "source" keeps the preset; sizes are even for H.264 and may be odd for PNG; free-size presets are unchanged.
  • RenderRules: 2 for a mismatched fixed preset.
  • Merge:
    • rotate on one side and a look on the other give no conflict and version 2;
    • both sides cropping give one camera.crop conflict;
    • a v3 side throws.

Done when:

  • the existing suites are green with no behaviour change;
  • dotnet build -c Release has no new warnings;
  • i18n check, xaml-lint and package-guard are green.

P1: Core geometry (orientation, straighten, proportions win, crop math, advisor)

Files:

  • src/Chronos.Core/Render/RenderGeometry.cs:
    • Create uses the view size and RenderSize.Of, and drops AspectFromPreset;
    • maxZoom includes c;
    • For composes stab⁻¹·O⁻¹·V with the crop in T;
    • ViewFor, ViewToFrame, EditableCrop and FootprintInView get their real bodies;
    • the clamp warnings are added.
  • src/Chronos.Core/Imaging/Geometry/FrameOrientation.cs, CropFrame.cs (Move, ResizeFrom, Refit, Clamp, FromRows/ToRows, Largest) and OrientationEdit.cs (turn, mirror and flip remapping crop, centres, roll and transposed aspect).
  • src/Chronos.Core/Advice/AdvisorRules.cs:452-474: the aspect is worked out on the oriented size.
  • src/Chronos.Core/Render/Diagnostics/SelfTestGeometryChecks.cs: proc.orient, proc.straighten, proc.portrait.
  • src/Chronos.Core/Render/Diagnostics/SelfTestRenderChecks.cs: proc.aspect is expected unchanged (it uses "source"); confirm it.
  • Tests in tests/Chronos.Core.Tests/:
    • Geometry/GeometryStageTests.cs, Geometry/Affine2DTests.cs, Geometry/AspectRatioTests.cs;
    • new: Geometry/FrameOrientationTests.cs, Geometry/CropFrameTests.cs, Geometry/OrientationEditTests.cs;
    • Render/RenderProcessingTests.cs (new cases; the :130 case stays, since it uses "source"), Render/RenderPipelineTests.cs:56, Render/SelfTestTests.cs (:9, :18);
    • Advice/AdvisorTests.cs.

Depends on: P0.

Tests (on Linux):

  • Exactness:
    • Turns of 90, 180 and 270 and mirror/flip at 1:1 are byte-equal to an index-permuted copy of a seeded texture, and the size swaps for odd turns.
    • Algebra: mirror² = I, turn⁴ = I, the turn·mirror parity.
  • Straighten:
    • It matches the analytic ramp within 2e-6.
    • With BorderMode.Transparent, alpha is 1 at every output pixel at ±15°.
    • WorkingLongEdge grows with c.
  • Create:
    • 4K at 9:16 gives 2160×3840; "source" with 4K gives 3840×2160.
    • A crop in T selects the same content after OrientationEdit (PSNR > 60 against the plain capture remapped).
    • Four right turns give the original canonical text.
  • CropFrame: move and resize stay locked to the ratio and clamped, with the 10 % minimum; Refit keeps the centre; FromRows/ToRows round trip.
  • Advisor: a portrait view after a turn advises 9:16.
  • Determinism: PNG output is byte-identical across runs with the transforms on.
  • Self-test: passes, with the count updated.

Done when: Core.Tests are green on Linux CI and Chronos.Tools selftest passes.

P2: Core look filter

Files:

  • src/Chronos.Core/Imaging/Color/LookFilter.cs: the implementation (one matrix, contrast and lift per look; the strength blend; Rec.709 luminance from ColorSpace; vectorised).
  • src/Chronos.Core/Render/FrameFinish.cs: only if validation or warnings need it.
  • src/Chronos.Core/Render/Diagnostics/SelfTestColourChecks.cs: proc.look.
  • tests/Chronos.Core.Tests/Imaging/LookFilterTests.cs and tests/Chronos.Core.Tests/Render/LookRenderTests.cs, both new.

Depends on: P0.

Tests:

  • Exact values:
    • The identity, a null look and strength 0 are byte-equal to no look.
    • Each look on flat linear patches matches its closed form within 1e-6, scalar against vectorised.
    • Mono gives R = G = B equal to Rec.709 luminance.
    • Strength 0.5 is the midpoint.
  • Order:
    • Values above 1 are kept, then the knee is applied.
    • An unknown name gives the identity plus LookIgnored.
    • A capture with a look equals FrameFinish applied to the plain capture.
    • A median stack with mono equals mono of the median.
  • Determinism: PNG is byte-identical across runs. Tolerances only; no cross-CPU golden bytes.

Done when: Core.Tests are green and the self-test passes.

P3: Preview and visual crop interaction

Files:

  • src/Chronos.Ui/Visuals/PreviewViewport.cs, PreviewSurface.cs and ViewportMath.cs (handle hit-test helpers).
  • src/Chronos.App/Editor/PreviewRenderer.cs: Source framing through ViewFor; the mask from EditableCrop or FootprintInView; the horizon and region overlays mapped; PreviewFrame gains ViewSize, LockRatio and EditCrop.
  • src/Chronos.App/Editor/EditorViewModel.cs: the Camera-step mask state, CropEditable, CropLockRatio, CommitCropCommand and IsStraightening. This package owns this file.
  • src/Chronos.App/Editor/CropCommit.cs (new), and src/Chronos.App/Sections/SequenceView.xaml and .xaml.cs.
  • src/Chronos.Tools/Commands/XamlLintCommand.cs.
  • Tests in tests/Chronos.App.Tests/: Visuals/ViewportMathTests.cs, Visuals/VisualsSmokeTests.cs, Editor/PreviewRendererTests.cs and Editor/EditorSmokeTests.cs.

Depends on: P0. Rebase on P1 and P2 before the parity tests.

Tests (Windows, App.Tests filtered on this PC):

  • Interaction:
    • Hit-test priority at three zoom levels.
    • A move followed by a corner resize keeps the ratio, and the event fires once with the clamped rect.
    • Esc cancels the drag.
    • One drag is one undo step, and keyboard nudges commit.
    • A read-only or newer-format project shows no handles.
  • Drawing: CopyPixels shows the handles where expected.
  • Preview:
    • Source framing with a 90° turn has its size swapped.
    • The mask equals EditableCrop.
    • A look changes only corrected.
    • Output framing against RenderFixture.CaptureAsync: PSNR > 40 with rotate, straighten and a look on.
    • The existing OutputFramingFollowsTheExportAspect case (square preset with "source") still passes, plus a new 9:16 case.
  • Layout: the preview tools fit in every language.

Done when: these tests are green on the PC and xaml-lint is green.

P4: Step controls

Files:

  • src/Chronos.App/Editor/CameraTab.cs; CropMargins.cs is deleted.
  • src/Chronos.App/Editor/SettingRows.cs: SwitchRow and IconActionsRow.
  • src/Chronos.App/Editor/EditorPanels.xaml: the new templates, and the straighten slider's focus/drag driving Editor.IsStraightening.
  • src/Chronos.App/Editor/ExposureTab.cs.
  • src/Chronos.App/Editor/EditorSession.cs: Orient(op), ResetFraming; ApplyPreset only checked.
  • src/Chronos.App/Editor/ExportTab.cs and ExportPlanner.cs; EditorSettings.cs only if needed.
  • Tests in tests/Chronos.App.Tests/Editor/: EditorTextTests.cs (the CropMargins test replaced), EditPathTests.cs, EditorSessionTests.cs, ExportPlannerTests.cs and CameraTabTests.cs (new).

Depends on: P0, plus the P1 bodies for the end-to-end checks. Overlap with P3: EditorPanels.xaml (P4) and SequenceView.xaml (P3) are different files. P4 does not touch EditorViewModel.cs.

Tests (Windows):

  • Orientation:
    • Rotate composes correctly with mirror and flip.
    • Rotate right four times gives the original canonical text.
    • Mirror maps crop x to 1−x−w.
    • An aspect change refits the crop.
  • Reset and look:
    • Reset framing clears exactly the six members.
    • A look back at the identity writes Look = null, and the version goes back to 1.
    • Strength shows n/a when the filter is None.
  • State: Camera and Exposure read Edited for the new values.
  • Export: shows an output size of 2160 × 3840 at 4K 9:16, while the preset name stays.
  • Rules: every control has a tooltip, and labels are at most 3 words in en and it.

Done when: these tests are green on the PC and i18n check is green (the old keys are still present).

P5: Server, nodes, routing, encoder limits, desktop gating

Files:

  • Server: src/Chronos.Server/Api/SystemEndpoints.cs, Api/JobEndpoints.cs, Jobs/RenderNodeService.cs and Jobs/RenderNodeAvailability.cs.
  • Data: src/Chronos.Data/Processing/ProcessingJobs.cs, RenderNodeClient.cs, ProjectStore.cs, Jobs/ManagedRenderJobHandler.cs and Jobs/RenderJobHandler.cs.
  • Encoders, only if the limits prove orientation-dependent: src/Chronos.Core/Export/EncoderSelector.cs and the MF provider.
  • Desktop gating: src/Chronos.App/Server/SyncHost.cs, src/Chronos.App/Editor/ServerJobs.cs and src/Chronos.App/Workspace/ProjectMenuViewModel.cs.
  • Tests: tests/Chronos.Server.Tests/Jobs/RenderNodeClientTests.cs, tests/Chronos.Server.Tests/Api/ProjectTests.cs, tests/Chronos.Data.Tests/Processing/RenderJobTests.cs and tests/Chronos.Data.Tests/Processing/ProjectStoreTests.cs.

Depends on: P0. RenderSize is already real there.

Tests (Linux):

  • Sizes: a 4K job at 9:16 is 2160×3840; a 90° turn swaps the size.
  • Nodes:
    • A registration without settingsFormat reads as 1, and that node never claims a v2 or proportions-win job; a format-2 node does.
    • AwaitsNode is false when only incompatible nodes are online.
  • Server:
    • server info announces 2.
    • Pushes of v1 and v2 are accepted; v3 gets 422 newer_format.
    • An over-format render fails with the localised key.
    • UpdateLockedAsync never raises a v1 project.

On Windows: the desktop gate is disabled, with its tooltip, against a fake ServerInfo without settingsFormat, and a portrait H.264 encode is checked on the dev PC.

Done when: Data and Server tests are green on Linux CI.

P6: Integration (captures, baselines, translations, key removal, review)

Files:

  • src/Chronos.App/Shell/ScreenCapture.cs, with new scenes:
    • the Camera step with a moved 9:16 mask and its handles;
    • a rotated and straightened view with the grid;
    • Exposure with the Sepia look and the wipe.
  • src/Chronos.App/DesignTime/SampleData.cs.
  • tests/Chronos.App.Tests/Windows/ScreenSmokeTests.cs.
  • tests/visual/baselines: re-accept edit-camera-*, edit-export-*, edit-exposure-* and edit-remote-*, and add the new scenes.
  • i18n/<36 other locales>/*.resx: the new keys.
  • Remove the obsolete en/it keys, then run dotnet run --project src/Chronos.Tools -- i18n prune.

Depends on: P1–P5.

Tests:

  • the full Release build with no new warnings;
  • every suite;
  • i18n check in all 38 locales;
  • xaml-lint, pe-check, package-guard and selftest;
  • Chronos.exe --capture, then Chronos.Tools screenshots diff (8/255, 0.05 %).

Then an adversarial review round and its fixes.

Done when: everything is green, Linux CI is green, the Windows suites are green on the PC, and the baselines are accepted.

P7 (last): Docs

Files:

  • docs/BRIEF.md:
    • §11.4, line 1032: "Presets bind resolution, aspect…" becomes "Presets bind a resolution class…; the chosen proportions win and a fixed-size preset adapts (4K at 9:16 = 2160×3840); 'source' keeps the preset's ratio".
    • §12.3, line 1181: Camera = "crop (visual, aspect-locked), aspect, rotation, mirror, flip, straighten, virtual camera keyframes"; Exposure adds "look (filter, strength)".
    • The amendment table (around :3017) gets a 2026-11 row "Owner review 1, R5/R6".
  • docs/ui/DESIGN.md and docs/ui/mockups/Editor.html cover the handles, the Rotation, Mirror, Flip and Straighten rows, the crop rows, the straighten grid, the Look rows and the Output size row. The draft starts in parallel right after P0, so P3 and P4 can check against it.
  • docs/CHANGELOG.md, upgrade notes:
    • proportions win changes the output size of projects with an explicit aspect and a fixed preset;
    • format 2 is written only when the new features are used, and older Chronos opens such projects read-only;
    • nodes and servers announce their settings format.
  • docs/STATUS.md at the phase gate.
  • docs/ARCHITECTURE.md: ownership of FrameOrientation, CropFrame, OrientationEdit, RenderSize, RenderRules, FrameFinish and LookFilter.
  • docs/requests/2026-10-15-owner-review-1.md: row 4 goes to done, with a link to the release.
  • docs/DECISIONS.md: final amendments only.

Depends on: P6.

Done when: the phase report with "how to try it" is written, the tagged release (Docker + .exe) is out, and the memory notes are updated, as the owner's publish rule requires.


Verification

  • Build: dotnet build -c Release, with no new warnings.
  • Tests on Linux CI:
    • dotnet run --project tests/Chronos.Core.Tests -- --junit out.xml
    • the same for Chronos.Data.Tests, Chronos.Server.Tests and Chronos.Tools.Tests.
  • Tools:
    • dotnet run --project src/Chronos.Tools -- i18n check
    • the same with xaml-lint, package-guard, pe-check and selftest.
  • Windows PC:
    • tests/Chronos.App.Tests, filtered: this PC hangs on the volume and shell tests.
    • Chronos.exe --capture, then screenshots diff.
  • How to try it:
    1. On the Camera step, drag and resize a 9:16 mask; the ratio stays locked.
    2. Rotate right, mirror, and straighten 3°; the mask keeps the content.
    3. On Exposure, choose Sepia at 60 % and compare with the wipe.
    4. On Export, choose 4K: Output size reads 2160 × 3840; render it and check the file.
    5. Open the project in v0.x (older): it is read-only.
    6. Render on a server running an older build: the button is disabled, with its reason.
    7. With a format-1 node online, the job is not claimed by it and the managed fallback runs.

Risks

  • Canonical or hash drift. This happens if a member is written at its default, declared before an existing member, or serialised outside ToJson. It would spawn External versions and show workspaces as Modified. P0's byte-identity and old-build tests pin it, together with the audit of ProjectJson.Default.ProjectSettings uses.
  • Proportions win changes existing outputs. A v1 project with an explicit non-source aspect and a fixed preset changes size, for example an advised 9:16 portrait at 4K going from 3840×2160 to 2160×3840. It is not gated by the stored format. Routing and the desktop's server gating cover new servers and nodes; an older desktop still renders at the preset ratio. This is in the CHANGELOG and DECISIONS.
  • Format 2 is user-visible. Older desktops open such projects read-only, and older servers refuse pushes and renders. This is intended by owner review 2 and pre-empted by the disabled buttons with a reason.
  • Portrait encoder limits. 2160×3840 exceeds the MF software H.264 maximum of 4096×2304 and may stop matching nodes whose limits are not orientation-symmetric. P5 checks this on the PC, and the Export step shows the capped mark.
  • Merge semantics. One side's turn or mirror and the other side's framing edit (crop, keyframes, offsets, aspect, keyframes of waiting photos) are one conflict at the orientation member, settled with that side's framing. Straighten and crop merge independently, which the cover zoom keeps valid. FitCrop stays as the safety net.
  • Preview drift. Shared Core calls (RenderGeometry.ViewFor/For, FrameFinish) and a PSNR parity test guard against it. That test runs only on Windows.
  • Source-framing cost. A non-identity transform adds two resamples per preview picture. The identity fast path and the preview long-edge cap limit it, and a crop drag updates only the overlay.
  • Cover zoom softens the picture: about 1.43× at 15° on 16:9 (cos 15° + 16/9 · sin 15°). It is folded into WorkingLongEdge, so the decode size compensates.
  • Linux CI skips App.Tests and screenshots. All crop, orientation, size and look math lives in Core and is gated on Linux. The UI packages are verified on the PC, where 156 armed baselines must be re-accepted (fonts, Europe/Rome).
  • i18n removals. A removed English key makes all 38 locales report orphans. Removals are concentrated in P6 with i18n prune. The rule of at most 3 words per label is checked only in review; i18n check enforces 30 characters.
  • Parallel overlap. Ownership is fixed:
    • RenderGeometry.cs: stubbed in P0, filled in P1.
    • PreviewRenderer.cs and EditorViewModel.cs: P3 only.
    • EditorPanels.xaml, CameraTab.cs and ExposureTab.cs: P4 only.
    • The en/it resx files: P0 adds, P6 removes.
    • SelfTest.cs: P0 only, with the partials split between P1 and P2.
  • Mouse conflicts. Handles, the divider, move, pan and double-click all start on the left button. The fixed priority, the cursors and the CropEditable gate keep them apart, and the keyboard and automation peer keep the crop accessible.