Merge pull request #11 from TimeWarpEngineering/dev

feat: release 1.0.0 - stable API, full Yoga test coverage, five engine fixes

Author: StevenTCramer

kanban/backlog/148-fix-flex-basis-fit-content-feature.md

@@ -0,0 +1,27 @@
+# Task 148 - Implement FixFlexBasisFitContent Experimental Feature
+
+## Summary
+
+Yoga's `ExperimentalFeature::FixFlexBasisFitContent` is not implemented (the
+C# `ExperimentalFeature` enum only carries `WebFlexBasis`). It gates two
+behaviors in `computeFlexBasisForChild` (CalculateLayout.cpp): a fit-content
+fix for positive resolved flex-basis, and skipping height-axis FitContent for
+non-measure container children inside scroll subtrees (prevents re-measure
+cascades in ScrollViews). One generated conformance test is skipped because of
+it (`flex_basis_in_scroll_content_container` in FlexBasisFitContentTests).
+
+Backlog: experimental in upstream Yoga, default-off, no consumer demand yet.
+Not a 1.0 blocker — documented as excluded in release notes.
+
+## Todo List
+
+- [ ] Add `FixFlexBasisFitContent` to the `ExperimentalFeature` enum
+- [ ] Port the two gated blocks in `FlexBasis.ComputeFlexBasisForChild` from
+      the current C++ (including the scroll-ancestor walk)
+- [ ] Re-run the test converter for FlexBasisFitContent to include the skipped
+      test; port any related upstream unit tests
+- [ ] Full suite green
+
+## Results
+
+(Add after completion)

kanban/backlog/149-auto-min-size-extension.md

@@ -0,0 +1,31 @@
+# Task 149 - Auto Min-Size Extension (Min-Content Measure)
+
+## Summary
+
+Upstream Yoga carries an auto-min-size extension implementing CSS Flexbox §4.5
+(automatic minimum size of flex items floored at min-content), gated behind the
+`YGErrataMinSizeUndefinedInsteadOfAuto` errata bit, with supporting node APIs:
+`YGNodeSetMinContentMeasureFunc`, `YGNodeHasMinContentMeasureFunc`,
+`YGNodeSet/GetMinContentWidth/Height`. None of this exists in the C# port.
+
+16 tests from `YGAutoMinSizeTest.cpp` were omitted during task 145 for this
+reason (the one portable test, `default_config_preserves_existing_shrink`, was
+ported and passes). See the omission list in the header of
+`test/timewarp-flexbox-tests/Algorithm/AutoMinSizeTests.cs`.
+
+Backlog: default-off behavior upstream, no consumer demand yet; documented as
+excluded in release notes alongside task 148 (FixFlexBasisFitContent).
+
+## Todo List
+
+- [ ] Add the errata bit to the `Errata` enum and thread it through
+      `Config.HasErrata` checks per the C++
+- [ ] Port the min-content measure plumbing on `Node`
+      (min-content measure func + static min-content width/height)
+- [ ] Port the algorithm changes (min-content flooring in
+      `boundAxisWithinMinAndMax` / flex basis paths - locate in current C++)
+- [ ] Port the 16 omitted YGAutoMinSizeTest tests; full suite green
+
+## Results
+
+(Add after completion)

kanban/to-do/140-release-1.0.0-beta.3.md kanban/done/140-release-1.0.0-beta.3.mdkanban/to-do/140-release-1.0.0-beta.3.md renamed to kanban/done/140-release-1.0.0-beta.3.md

@@ -16,8 +16,11 @@ verified: dll + readme + logo, MIT license, version 1.0.0-beta.3.
       succeeded ("Your package was pushed" to nuget.pkg.github.com/TimeWarpEngineering)
 - [x] Release notes state the API is entirely new (beta.2 was the deleted
       `FlexNode`/`FlexLayoutEngine` implementation) and list known gaps.
-- [ ] Verify the package installs into a consumer project (needs a PAT with
-      read:packages; push to the feed itself is confirmed via the workflow log)
+- [x] Verify the package installs into a consumer project — verified 2026-07-04
+      against nuget.org with 1.0.0-beta.4 (plain `dotnet add package`, no PAT):
+      the readme example runs and produces the documented output. (The repo has
+      since moved to public + nuget.org Trusted Publishing via tasks 141/143;
+      beta.4 superseded beta.3 as the first nuget.org release.)
 
 ## Toward stable 1.0 (follow-ups, not blockers for beta.3)
 
@@ -27,6 +30,10 @@ verified: dll + readme + logo, MIT license, version 1.0.0-beta.3.
 - [ ] Text-measurement test helper to unlock skipped IntrinsicSize tests
 - [ ] Enable GenerateDocumentationFile so the package ships XML docs
 
-## Results
+## Results (2026-07-04)
 
-(Add after completion)
+Complete. beta.3 published to GitHub Packages on 2026-07-03; the follow-up
+1.0.0-beta.4 (2026-07-04) became the first nuget.org release through the new
+Trusted Publishing pipeline, and consumer installation was verified against
+nuget.org. Stable-1.0 follow-ups moved to their own tasks (139 done, 141 done,
+142 done, 143 in progress).

…s/143-timewarp-software-regen-trigger.md …e/143-timewarp-software-regen-trigger.mdkanban/in-progress/143-timewarp-software-regen-trigger.md renamed to kanban/done/143-timewarp-software-regen-trigger.md kanban/in-progress/143-timewarp-software-regen-trigger.md renamed to kanban/done/143-timewarp-software-regen-trigger.md

@@ -60,9 +60,10 @@ site without waiting for the nightly cron backstop.
 - [x] Dry-run: `workflow_dispatch` the pipeline without a release; then cut the next
       release and verify the dispatch lands (timewarp-software Actions shows a
       `rebuild` repository_dispatch run) and the package page appears
-- [ ] After task 142 lands, verify the flexbox skill shows on
-      https://timewarp.software/ skills index (or add this repo to
-      `extraSkillRepos` if it remains off nuget.org)
+- [x] After task 142 lands, verify the flexbox skill shows on
+      https://timewarp.software/ skills index — VERIFIED 2026-07-04: skill live at
+      /skills/flexbox/SKILL.md and in the skills index; package page live at
+      /packages/timewarp.flexbox/
 
 ## Dependencies
 
@@ -97,3 +98,31 @@ Remaining items require owner action: make the repo public, register
 TimeWarp.Flexbox for nuget.org Trusted Publishing under TimeWarp.Enterprises,
 then cut the next release and verify the package page + flexbox skill appear
 on https://timewarp.software/.
+
+## Release-chain verification (2026-07-04, v1.0.0-beta.4)
+
+- Release pipeline green end-to-end in Actions: OIDC login, version check,
+  pack, "Your package was pushed" to nuget.org, "timewarp-software rebuild
+  dispatched" (org App token mint worked).
+- Package live on nuget.org: listed=true, gallery page 200, consumer install
+  verified (plain dotnet add package; readme example output exact).
+- Site rebuild runs complete successfully on each dispatch.
+- REMAINING: nuget.org's SEARCH index (which drives the site's owner-search
+  catalog) lags for brand-new package ids - still 0 hits ~2h after push.
+  Once it indexes, any rebuild (manual dispatch or the nightly cron) picks up
+  the package page and the flexbox skill automatically. Verify then check the
+  final box below.
+
+## Results (2026-07-04)
+
+Complete and verified end-to-end with v1.0.0-beta.4:
+release event -> OIDC Trusted Publishing -> push to nuget.org -> rebuild
+dispatch -> site rebuild -> https://timewarp.software/ shows the
+timewarp.flexbox package page and the flexbox skill.
+
+Follow-up discovered in the process: the dispatch races NuGet's SEARCH index
+(the site catalog's data source) — a brand-new package id took ~3.5h to become
+searchable, so the release-triggered rebuilds ran too early and a manual
+re-dispatch was needed. Fix proposed on the receiver side (poll the search
+index for the payload's exact version before building, 30-min bound, nightly
+backstop unchanged): timewarp-software PR #23.

kanban/done/144-api-surface-tightening-for-1.0.md

@@ -0,0 +1,86 @@
+# Task 144 - API Surface Tightening for 1.0
+
+## Summary
+
+The package currently exports 93 public types, of which only ~a dozen are the
+intended consumer API. The rest are engine internals that are public only
+because the Yoga port translated C++ file-by-file. 1.0.0 freezes the public
+surface under semver, so this must happen BEFORE the stable release —
+internalizing anything afterward is a breaking change. This is the only
+blocker for 1.0 (see task 147).
+
+## Intended public surface (keep public)
+
+`Node`, `Style`, `Config`, `CalculateLayout`, `LayoutResults`,
+`StyleLength`, `StyleSizeLength`, `YGValue`, `YGSize`, `FloatOptional`,
+`YogaAssertException`, the delegates (`MeasureFunc`, `BaselineFunc`,
+`DirtiedFunc`, `CloneNodeFunc`, `YogaLogHandler`), and the enums
+(`FlexDirection`, `Justify`, `Align`, `Wrap`, `Edge`, `Gutter`, `Dimension`,
+`PhysicalEdge`, `Direction`, `PositionType`, `Overflow`, `Display`,
+`BoxSizing`, `Unit`, `MeasureMode`, `NodeType`, `Errata`,
+`ExperimentalFeature`, `LogLevel`). Review each remaining public member on
+these types too (e.g. `Node.CloneChildrenIfNeeded`, layout setters) — some
+are engine plumbing.
+
+## Todo List
+
+- [x] Internalize the algorithm machinery: `AbsoluteLayout`, `AlignUtils`,
+      `Baseline`, `BoundAxis`, `Cache`, `CalculateLayoutCore`, `FlexBasis`,
+      `FlexDirectionUtils`, `FlexDistribution`, `FlexLine`, `JustifyContent`,
+      `LayoutHelpers`, `MeasureNode`, `PixelGrid`, `TrailingPosition`,
+      `SizingMode`(+extensions), `LayoutData`, `LayoutPassReason`(+extensions)
+- [x] Internalize storage/infra: `StyleValuePool`, `StyleValueHandle`,
+      `SmallValueBuffer`(+generic), `LayoutableChildren`, `CachedMeasurement`,
+      `Comparison`, `YogaEnums`(+extensions), `OrdinalCountAttribute`,
+      `YogaEvent`/`LayoutData` event plumbing, `YogaLog`, `YogaAssert`
+- [x] **Eliminate the mutable public static wiring**: `FlexBasis.CalculateLayoutInternal`
+      is a public static settable delegate — any consumer can reassign it and break
+      the engine globally. Make the wiring internal (or replace the delegate
+      indirection with a direct internal call; it exists only to break a
+      circular file dependency from the C++ port)
+- [x] Add `[assembly: InternalsVisibleTo("TimeWarp.Flexbox.Tests")]` — the unit
+      tests exercise the machinery directly (keep them; they're ported Yoga tests)
+- [x] Confirm naming decisions that 1.0 freezes: `YGValue`/`YGSize` Yoga-parity
+      names (recommended: keep — they signal lineage), `CalculateLayout.Calculate`
+      static entry point vs. a `Node.CalculateLayout()` instance convenience
+      (consider adding the instance method; additive later, but nicer at 1.0)
+- [x] Rebuild + full suite (1335/0/3 pins behavior), AOT smoke, `dotnet pack`
+      and inspect the package's public API (e.g. dotnet-inspect) to confirm the
+      final surface
+- [x] Update the flexbox skill / readme if any referenced type changed visibility
+
+## Notes
+
+- The 530 generated conformance tests use only the consumer API — they are the
+  guarantee that internalization broke nothing behavioral.
+- After this task, the public surface should be reviewable in one screenful.
+
+## Results (2026-07-04)
+
+Public surface reduced from 93 to 39 types: 19 enums, 6 value types
+(YGValue, YGSize, FloatOptional, StyleLength, StyleSizeLength,
+ExperimentalFeatureSet), 5 delegates, 9 classes (Node, Style, Config,
+CalculateLayout, LayoutResults, Comparison, StyleLength/StyleSizeLength
+extensions, YogaAssertException). All algorithm machinery, storage internals,
+event system, and debug utilities are now internal; the mutable
+FlexBasis.CalculateLayoutInternal delegate is internal with the type.
+
+Deviations from the plan, deliberate:
+- `Comparison` kept public: tiny, useful (IsUndefined/IsDefined for NaN
+  semantics), documented in the flexbox skill.
+- `ExperimentalFeatureSet` kept public (readonly struct surfaced by
+  Config.EnabledExperiments).
+
+API improvements while the surface was open:
+- `Node.GetChild(int)` now returns `Node` (was ILayoutableNode); the duplicate
+  `GetChildNode` removed; ILayoutableNode members explicitly implemented.
+- Added `Node.CalculateLayout(availableWidth = NaN, availableHeight = NaN,
+  ownerDirection = LTR)` instance convenience; docs/skill updated.
+- InternalsVisibleTo("timewarp-flexbox-tests") added; MockNode test helper
+  internalized — which removed 5 phantom Fixie-discovered entries (suite is
+  now a clean 1333 passed / 0 failed / 0 skipped; previously 1335+3 included
+  MockNode's methods).
+
+Verified: gated Release build zero warnings, suite 1333/0/0, AOT smoke native
+binary PASS, layout demo runs, dotnet format stable, ganda audit 22/22.
+Naming frozen deliberately: YGValue/YGSize Yoga-parity names kept.

kanban/done/145-port-remaining-yoga-unit-tests.md

@@ -0,0 +1,77 @@
+# Task 145 - Port Remaining Hand-Written Yoga Unit Tests
+
+## Summary
+
+Task 138 ported the generated conformance suite (all 25 files) and the four
+high-priority hand-written suites (Measure, MeasureCache, MeasureMode,
+Relayout). The remaining hand-written Yoga unit tests are still unported —
+coverage gaps, not known bugs. Recommended before 1.0 but not blocking
+(task 147 may proceed in parallel).
+
+## Source Files
+
+Yoga clone `tests/` directory (clone facebook/yoga; see the conventions and
+API mapping in `kanban/done/138-integration-testing.md` and the agent prompt
+patterns used there):
+
+- YGBaselineFuncTest.cpp, YGAlignBaselineTest.cpp (baseline callbacks)
+- YGAspectRatioTest.cpp
+- YGEdgeTest.cpp, YGComputedMarginTest.cpp, YGComputedPaddingTest.cpp
+- YGHadOverflowTest.cpp
+- YGRoundingFunctionTest.cpp, YGRoundingMeasureFuncTest.cpp, YGScaleChangeTest.cpp
+- YGZeroOutLayoutRecursivelyTest.cpp
+- YGPersistenceTest.cpp, YGPersistentNodeCloningTest.cpp
+- YGDirtiedTest.cpp, YGDirtyMarkingTest.cpp (partially covered by NodeTests)
+- YGNodeChildTest.cpp, YGCloneNodeTest.cpp, YGNodeCallbackTest.cpp
+- FlexGapTest.cpp, YGAutoMinSizeTest.cpp, YGDefaultValuesTest.cpp
+
+## Todo List
+
+- [x] Port the suites above to `test/timewarp-flexbox-tests/` (Fixie
+      conventions, snake_case Yoga names, 2-space indent)
+- [x] Omit tests using unsupported features (GTEST_SKIP, experimental features
+      other than WebFlexBasis) and record omissions
+- [x] Expect failures to be real port defects — do not bend tests; fix the
+      engine against the C++ (the task-138 pattern: every failure found a
+      genuine mistranslation)
+- [x] Full suite green; note the new test count
+
+## Results
+
+(Add after completion)
+
+## Results (2026-07-04)
+
+All 21 suites ported (123 new tests; suite grew 1333 -> 1456, all passing).
+Ported via three parallel worktree agents; every failure was treated as an
+engine defect and fixed against the C++. FIVE genuine engine defects found
+and fixed:
+
+1. PixelGrid rounding compared the fractional part as float, not double -
+   `RoundValueToPixelGrid(-3.5001, 1, false, false)` returned -3 instead of
+   -4 (float cast collapsed the 1e-4 tolerance boundary). Now uses the
+   double InexactEquals overload like C++.
+2. ZeroOutLayoutRecursively only zeroed dimensions; C++ resets the ENTIRE
+   layout (positions, margins, cached measurements) via `getLayout() = {}`
+   and calls cloneChildrenIfNeeded before recursing. Also fixed the missing
+   performLayout guard at the display:none call site (C++ avoids mutating
+   during measure-only passes to prevent leaked hasNewLayout flags).
+3. Node.Clone() kept the source's Owner; C++ YGNodeClone clears it (a clone
+   starts detached).
+4. CloneChildrenIfNeeded missed the branch where a cloned child is itself
+   display:contents (its children must be cloned recursively).
+5. CleanupContentsNodesRecursively diverged wholesale: missing
+   didPerformLayout parameter, missing CloneContentsChildrenIfNeeded /
+   CloneChildrenIfNeeded calls, only zeroed dimensions instead of full
+   layout reset, and wrongly recursed into regular (non-contents) children.
+   Rewritten to C++ parity; call sites pass the correct flag per C++.
+
+Three stale hand-written tests that codified the old behaviors were updated.
+
+Recorded omissions: 16 YGAutoMinSizeTest tests (auto-min-size extension:
+errata bit + min-content measure funcs not in the engine - candidate for a
+backlog task), 3 free-semantics tests (no GC equivalent), 1 duplicate
+already in NodeTests, 1 null-return GetChild assertion (C# throws).
+
+Verified: gated Release build clean, suite 1456/0/0, AOT smoke PASS,
+dotnet format stable, ganda audit 22/22.

kanban/done/146-text-measurement-intrinsic-size-tests.md

@@ -0,0 +1,40 @@
+# Task 146 - Text-Measurement Helper and IntrinsicSize Tests
+
+## Summary
+
+~15 of Yoga's generated IntrinsicSize conformance tests are skipped because
+they need a text-measurement context: Yoga's test harness attaches an
+"intrinsic text" measure function (via `YGNodeSetContext` + a shared measure
+helper in `tests/util/TestUtil`) that simulates word-wrapping text. Build the
+C# equivalent and unlock those tests. Recommended before 1.0 but not blocking.
+
+## Todo List
+
+- [x] Study Yoga's text-measure test helper (gentest fixtures use an
+      "intrinsic" measure function that wraps words at ~10px per char, and the
+      C++ tests pass the text via node context)
+- [x] Implement an equivalent helper in the test project (e.g.
+      `IntrinsicTextMeasure.MeasureFunc` reading `Node.Context` as the text)
+- [x] Extend `runfiles/port-generated-tests.cs` to translate
+      `YGNodeSetContext(node, (void*)"...")` + `YGNodeSetMeasureFunc(node,
+      IntrinsicSizeMeasure)` instead of skipping those tests
+- [x] Re-run the converter for IntrinsicSize; fix any engine divergences the
+      new tests expose (compare against C++ as usual)
+- [x] Full suite green; update skill/readme "known gaps" wording once covered
+
+## Results (2026-07-04)
+
+Complete. `test/timewarp-flexbox-tests/Generated/IntrinsicSizeMeasure.cs` is a
+faithful port of Yoga's tests/util/TestUtil.cpp IntrinsicSizeMeasure (10px per
+char, word-wrap height simulation, text via Node.Context). The converter now
+translates `YGNodeSetContext(node, (void*)"...")` -> `node.Context = "..."`
+and the IntrinsicSizeMeasure SetMeasureFunc pattern, and emits 2-space
+indentation matching .editorconfig.
+
+IntrinsicSize conversion went from 5 to 17 tests (12 text-measurement tests
+unlocked); the remaining 28 exclusions are all upstream GTEST_SKIPs
+(intrinsic sizing keywords Yoga itself disables). ALL 12 new tests passed on
+the first run - no engine changes were needed for intrinsic text measurement.
+Suite: 1468/0/0; format stable; audit 22/22. Neither the readme nor the skill
+listed this as a gap, so no doc wording changes were needed (the 1.0 release
+notes simply won't carry the beta.4 caveat).

kanban/in-progress/147-release-1.0.0.md

@@ -0,0 +1,46 @@
+# Task 147 - Release 1.0.0 (Stable)
+
+## Summary
+
+Publish the first stable release. The engine quality is release-ready
+(Yoga-conformance-verified, AOT-guaranteed, benchmarked, zero-dependency,
+documented, pipeline proven with beta.3/beta.4). The single hard blocker is
+task 144 (API surface tightening) because 1.0.0 freezes the public API under
+semver. Tasks 145/146 are recommended-but-optional coverage work — either land
+them first or note the gaps in the release notes.
+
+## Dependencies
+
+- **Task 144 (BLOCKER)** — API surface tightening; do not tag 1.0.0 before it
+- Task 145 (recommended) — remaining Yoga unit tests
+- Task 146 (recommended) — intrinsic text-measurement coverage
+- Some beta soak time is prudent: beta.4 shipped 2026-07-04 with zero external
+  usage feedback so far
+
+## Todo List
+
+- [ ] Confirm task 144 merged; public API reviewed and final
+- [ ] Decide on 145/146: land first, or list as known gaps in release notes
+- [ ] Bump `<Version>` in `source/Directory.Build.props` to `1.0.0`
+- [ ] Update readme + skill install snippets (drop `--prerelease`; version 1.0.0)
+- [ ] PR dev -> master, green CI, merge
+- [ ] `gh release create v1.0.0` (NOT --prerelease). Release notes: stable API
+      commitment statement; conformance/AOT/perf highlights; anything excluded
+      (FixFlexBasisFitContent, intrinsic text if 146 not done); breaking changes
+      vs beta.4 from the 144 internalization (beta consumers using internals)
+- [ ] Verify the chain: nuget.org (stable channel now — the site's
+      `prerelease=false` owner search picks it up), site rebuild (the PR #23
+      wait-gate handles search-index lag), package page shows stable version
+- [ ] Consumer install check without `--prerelease`
+
+## Notes
+
+- First STABLE version: the site's stable-channel search
+  (`prerelease=false`) will list it — until now flexbox only existed in the
+  prerelease channel.
+- Semver discipline starts here: internalization or renames after this
+  require 2.0.0.
+
+## Results
+
+(Add after completion)