fix: preserve authored library content before roadmaps

config/roadmaps/geo-parser.json

@@ -24,22 +24,22 @@
     {
       "version": "5.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2027-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2027-12-31",
       "securitySupportUntil": "2028-12-31",
-      "php": null,
-      "notes": "Release forecast: January 2027; exact date unannounced. Previously listed PHP target: 8.4 and 8.5; Composer constraint unannounced."
+      "php": "^8.4",
+      "notes": null
     },
     {
       "version": "6.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2028-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2028-12-31",
       "securitySupportUntil": "2029-12-31",
-      "php": null,
-      "notes": "Release forecast: January 2028; exact date unannounced. Previously listed PHP target: 8.5; Composer constraint unannounced."
+      "php": "^8.5",
+      "notes": null
     }
   ]
 }

config/roadmaps/spatial-core.json

@@ -14,21 +14,21 @@
     {
       "version": "2.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2027-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2027-12-31",
       "securitySupportUntil": "2028-12-31",
-      "php": null,
+      "php": "^8.4",
       "notes": "Release forecast: September 2026; exact date unannounced. Previously listed PHP target: 8.4 to 8.6; Composer constraint unannounced."
     },
     {
       "version": "3.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2028-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2028-12-31",
       "securitySupportUntil": "2029-12-31",
-      "php": null,
+      "php": "^8.5",
       "notes": "Release forecast: January 2028; exact date unannounced. Previously listed PHP target: 8.5 and 8.6; Composer constraint unannounced."
     }
   ]

config/roadmaps/spatial-decoder.json

@@ -4,7 +4,7 @@
     {
       "version": "1.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2027-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2027-12-31",
       "securitySupportUntil": "2028-12-31",
@@ -14,11 +14,11 @@
     {
       "version": "2.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2028-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2028-12-31",
       "securitySupportUntil": "2029-12-31",
-      "php": null,
+      "php": "^8.5",
       "notes": "Release forecast: January 2028; exact date unannounced. Previously listed PHP target: 8.5; Composer constraint unannounced."
     }
   ]

config/roadmaps/spatial-encoder.json

@@ -4,7 +4,7 @@
     {
       "version": "1.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2027-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2027-12-31",
       "securitySupportUntil": "2028-12-31",
@@ -14,11 +14,11 @@
     {
       "version": "2.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2028-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2028-12-31",
       "securitySupportUntil": "2029-12-31",
-      "php": null,
+      "php": "^8.5",
       "notes": "Release forecast: January 2028; exact date unannounced. Previously listed PHP target: 8.5; Composer constraint unannounced."
     }
   ]

config/roadmaps/spatial-transformer.json

@@ -4,7 +4,7 @@
     {
       "version": "1.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2027-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2027-12-31",
       "securitySupportUntil": "2028-12-31",
@@ -14,7 +14,7 @@
     {
       "version": "2.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2028-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2028-12-31",
       "securitySupportUntil": "2029-12-31",

config/roadmaps/spatial-types.json

@@ -4,7 +4,7 @@
     {
       "version": "1.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2026-12-01",
       "releaseDate": null,
       "activeSupportUntil": "2027-12-31",
       "securitySupportUntil": "2028-12-31",
@@ -14,11 +14,11 @@
     {
       "version": "2.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2028-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2028-12-31",
       "securitySupportUntil": "2029-12-31",
-      "php": null,
+      "php": "^8.5",
       "notes": "Release forecast: January 2028; exact date unannounced. Previously listed PHP target: 8.5; Composer constraint unannounced."
     }
   ]

config/roadmaps/spatial-validator.json

@@ -4,7 +4,7 @@
     {
       "version": "1.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2026-12-01",
       "releaseDate": null,
       "activeSupportUntil": "2027-12-31",
       "securitySupportUntil": "2028-12-31",
@@ -14,11 +14,11 @@
     {
       "version": "2.x",
       "status": "planned",
-      "plannedReleaseDate": null,
+      "plannedReleaseDate": "2028-01-01",
       "releaseDate": null,
       "activeSupportUntil": "2028-12-31",
       "securitySupportUntil": "2029-12-31",
-      "php": null,
+      "php": "^8.5",
       "notes": "Release forecast: January 2028; exact date unannounced. Previously listed PHP target: 8.5; Composer constraint unannounced."
     }
   ]

config/roadmaps/wkb-parser.json

@@ -19,7 +19,7 @@
       "activeSupportUntil": "2026-12-31",
       "securitySupportUntil": "2027-12-31",
       "php": "^8.1",
-      "notes": null
+      "notes": "This library will be deprecated after 1st January 2027 and it will be replaced by the Spatial Decoder library."
     }
   ]
 }

config/roadmaps/wkt-parser.json

@@ -19,7 +19,7 @@
       "activeSupportUntil": "2026-12-31",
       "securitySupportUntil": "2027-12-31",
       "php": "^8.1",
-      "notes": null
+      "notes": "This library will be deprecated after 1st January 2027 and it will be replaced by the Spatial Decoder library."
     }
   ]
 }

docs/geo-parser/index.md

@@ -4,7 +4,3 @@ description: Planned evolution of LongitudeOne Geo Parser across major releases.
 ---
 
 This roadmap shows announced support dates and release forecasts for geo-parser.
-
-Dates and Composer constraints come from the [shared roadmap configuration](../shared/support-timeline-generation.md#maintaining-library-roadmaps).
-Support dates retain the existing roadmap commitments. Monthly release forecasts remain approximate until an exact date is announced.
-Actual initial release dates are verified against the [published releases](https://github.com/longitude-one/geo-parser/releases).

docs/shared/support-timeline-generation.md

@@ -161,14 +161,17 @@ node scripts/generate-roadmap-timeline.mjs tests/fixtures/roadmaps/example-libra
 
 Edit `config/roadmaps/<library>.json` to update a roadmap. Both the SVG and table consume that file on the next build.
 The library landing page is `docs/<library>/index.md`. Keep its required `title` and `description` front matter appropriate to the library.
-The build replaces the entire body with the generated timeline and table in both HTML and portable Markdown; it does not append to existing prose.
+The build preserves the complete authored body in its original order in both HTML and portable Markdown.
+Generated roadmap text, timeline, support table and documentation-version links follow all authored headings, prose, lists, links, images and code blocks.
+Repeated builds do not duplicate either part; configuration changes refresh only the generated content.
 Source files are not rewritten during the build. Version landing pages such as `docs/<library>/v2/index.md` remain separate and unchanged.
 Do not keep a separate library-level `roadmap.md` page or a hand-written support table.
 
 A missing library JSON file, a blank file, an empty JSON object (`{}`), or a valid configuration with no branches displays:
 
 > The roadmap for this library has not been established yet.
 
+The default message and any documentation-version links follow the complete authored body.
 No timeline or support table is generated in that case, and a previously generated image is removed on the next export.
 A populated branch list remains configured even if every date is `null`. Malformed non-empty JSON, invalid populated data,
 and configurations for unknown libraries fail the build with an error. An otherwise empty branch list must still satisfy the full schema.

docs/spatial-core/index.md

@@ -4,7 +4,3 @@ description: Planned evolution of LongitudeOne Spatial Core across major release
 ---
 
 This roadmap shows announced support dates and release forecasts for spatial-core.
-
-Dates and Composer constraints come from the [shared roadmap configuration](../shared/support-timeline-generation.md#maintaining-library-roadmaps).
-Support dates retain the existing roadmap commitments. Monthly release forecasts remain approximate until an exact date is announced.
-Actual initial release dates are verified against the [published releases](https://github.com/longitude-one/spatial-core/releases).

docs/spatial-decoder/index.md

@@ -4,6 +4,3 @@ description: Planned evolution of LongitudeOne Spatial Decoder across major rele
 ---
 
 This roadmap shows announced support dates and release forecasts for spatial-decoder.
-
-Dates and Composer constraints come from the [shared roadmap configuration](../shared/support-timeline-generation.md#maintaining-library-roadmaps).
-Support dates retain the existing roadmap commitments. Monthly release forecasts remain approximate until an exact date is announced.

docs/spatial-encoder/index.md

@@ -4,6 +4,3 @@ description: Planned evolution of LongitudeOne Spatial Encoder across major rele
 ---
 
 This roadmap shows announced support dates and release forecasts for spatial-encoder.
-
-Dates and Composer constraints come from the [shared roadmap configuration](../shared/support-timeline-generation.md#maintaining-library-roadmaps).
-Support dates retain the existing roadmap commitments. Monthly release forecasts remain approximate until an exact date is announced.

docs/spatial-transformer/index.md

@@ -4,6 +4,3 @@ description: Planned evolution of LongitudeOne Spatial Transformer across major
 ---
 
 This roadmap shows announced support dates and release forecasts for spatial-transformer.
-
-Dates and Composer constraints come from the [shared roadmap configuration](../shared/support-timeline-generation.md#maintaining-library-roadmaps).
-Support dates retain the existing roadmap commitments. Monthly release forecasts remain approximate until an exact date is announced.

docs/spatial-types/index.md

@@ -4,6 +4,3 @@ description: Planned evolution of LongitudeOne Spatial Types across major releas
 ---
 
 This roadmap shows announced support dates and release forecasts for spatial-types.
-
-Dates and Composer constraints come from the [shared roadmap configuration](../shared/support-timeline-generation.md#maintaining-library-roadmaps).
-Support dates retain the existing roadmap commitments. Monthly release forecasts remain approximate until an exact date is announced.

docs/spatial-validator/index.md

@@ -4,8 +4,3 @@ description: Planned evolution of LongitudeOne Spatial Validator across major re
 ---
 
 This roadmap shows announced support dates and release forecasts for spatial-validator.
-
-See the [1.x documentation](./v1/index.md) for the planned first major version.
-
-Dates and Composer constraints come from the [shared roadmap configuration](../shared/support-timeline-generation.md#maintaining-library-roadmaps).
-Support dates retain the existing roadmap commitments. Monthly release forecasts remain approximate until an exact date is announced.

docs/wkb-parser/index.md

@@ -5,6 +5,6 @@ description: Planned evolution of LongitudeOne WKB Parser across major releases.
 
 This roadmap shows announced support dates and release forecasts for wkb-parser.
 
-Dates and Composer constraints come from the [shared roadmap configuration](../shared/support-timeline-generation.md#maintaining-library-roadmaps).
-Support dates retain the existing roadmap commitments. Monthly release forecasts remain approximate until an exact date is announced.
-Actual initial release dates are verified against the [published releases](https://github.com/longitude-one/wkb-parser/releases).
+After the 1st January 2027, WKB Parser will be deprecated and only receive security support until 31st December 2027.
+The library will be replaced by the [Spatial Decoder](../spatial-decoder/index.md) library and its WKB Decoder strategy,
+which will provide a more comprehensive and robust solution for decoding Well-Known Binary (WKB) into PHP spatial objects.

docs/wkt-parser/index.md

@@ -5,6 +5,6 @@ description: Planned evolution of LongitudeOne WKT Parser across major releases.
 
 This roadmap shows announced support dates and release forecasts for wkt-parser.
 
-Dates and Composer constraints come from the [shared roadmap configuration](../shared/support-timeline-generation.md#maintaining-library-roadmaps).
-Support dates retain the existing roadmap commitments. Monthly release forecasts remain approximate until an exact date is announced.
-Actual initial release dates are verified against the [published releases](https://github.com/longitude-one/wkt-parser/releases).
+After the 1st January 2027, WKT Parser will be deprecated and only receive security support until 31st December 2027.
+The library will be replaced by the [Spatial Decoder](../spatial-decoder/index.md) library and its WKT Decoder strategy,
+which will provide a more comprehensive and robust solution for decoding Well-Known Text (WKT) into PHP spatial objects.

scripts/roadmap-publication.mjs

@@ -70,8 +70,11 @@ export function appendRoadmapSupport(tree, sourcePath, roadmaps, { html = false
   const library = sourcePath.split('/')[0];
   if (!Object.hasOwn(roadmaps, library)) return;
   const { roadmap, versions } = roadmaps[library];
-  // Keep source metadata, replacing every body node. Reapplying is idempotent.
-  tree.children = [...tree.children.filter(({ type }) => type === 'yaml'), ...roadmapSupportNodes(roadmap, { library, versions, html })];
+  // Refresh only build-owned nodes; authored content (including metadata) stays in order.
+  const authored = tree.children.filter((node) => !node.data?.generatedRoadmapSupport);
+  const generated = roadmapSupportNodes(roadmap, { library, versions, html });
+  for (const node of generated) node.data = { ...node.data, generatedRoadmapSupport: true };
+  tree.children = [...authored, ...generated];
 }
 
 export default function remarkRoadmapSupport({ roadmaps, docsDirectory }) {

tests/export-markdown.test.mjs

@@ -27,7 +27,7 @@ test('export generates roadmap images and portable support tables from one confi
   }] };
   const { root, run } = await fixture(t, {
     'docs/index.md': document('Home', 'Home.', '[Roadmap](./example-library/index.md)'),
-    'docs/example-library/index.md': document('Example Library', 'Release and support roadmap.', 'Stale body must be replaced.'),
+    'docs/example-library/index.md': document('Example Library', 'Release and support roadmap.', '## Introduction\n\nAuthored introduction with [version](./v1/index.md).\n\n- First\n- Second\n\n```php\n$example = 1;\n```\n\nFinal authored paragraph.'),
     'docs/example-library/v1/index.md': document('Version 1', 'Version documentation.'),
     'config/roadmaps/window.json': JSON.stringify({ startDate: '2024-01-01', endDate: '2029-12-31' }),
     'config/roadmaps/example-library.json': JSON.stringify(roadmap),
@@ -38,7 +38,10 @@ test('export generates roadmap images and portable support tables from one confi
   await exportRoadmap();
   const output = await readFile(path.join(root, '.generated-markdown/example-library/index.md'), 'utf8');
   assert.match(output, /2027-02-01 \(forecast\)/);
-  assert.doesNotMatch(output, /Stale body must be replaced|Get started/);
+  assert.ok(output.indexOf('Final authored paragraph.') < output.indexOf('## Release timeline'));
+  assert.match(output, /\[version\]\(v1\/index\.md\)/);
+  assert.match(output, /```php\n\$example = 1;/);
+  const source = await readFile(path.join(root, 'docs/example-library/index.md'), 'utf8');
   assert.match(output, /\[1\.x\]\(v1\/index\.md\)/);
   assert.match(output, /\^8.4.*\^8.5/);
   assert.match(output, /\.\.\/assets\/roadmaps\/example-library.svg/);
@@ -57,7 +60,20 @@ test('export generates roadmap images and portable support tables from one confi
   const updated = await readFile(path.join(root, '.generated-markdown/example-library/index.md'), 'utf8');
   assert.notEqual(updated, original);
   assert.match(updated, /2027-03-01 \(forecast\)/);
+  assert.equal(updated.slice(0, updated.indexOf('## Release timeline')), output.slice(0, output.indexOf('## Release timeline')));
+  assert.equal(await readFile(path.join(root, 'docs/example-library/index.md'), 'utf8'), source);
   assert.match(await readFile(path.join(root, 'static/assets/roadmaps/example-library.svg'), 'utf8'), /2027-03-01/);
+  for (const configuration of [null, '', '{}', JSON.stringify({ ...roadmap, branches: [] })]) {
+    const filename = path.join(root, 'config/roadmaps/example-library.json');
+    if (configuration === null) await rm(filename);
+    else await writeFile(filename, configuration);
+    await exportRoadmap();
+    const fallback = await readFile(path.join(root, '.generated-markdown/example-library/index.md'), 'utf8');
+    assert.ok(fallback.indexOf('Final authored paragraph.') < fallback.indexOf('The roadmap for this library'));
+    assert.ok(fallback.indexOf('The roadmap for this library') < fallback.indexOf('## Documentation versions'));
+    assert.doesNotMatch(fallback, /## Release timeline|## Branch support/);
+    assert.equal(await readFile(path.join(root, 'docs/example-library/index.md'), 'utf8'), source);
+  }
 });
 
 function document(title, description, body = '', extraMetadata = '') {
@@ -143,14 +159,16 @@ async function landingFixture(t, entryDocument = 'index.md') {
   return { ...result, exportLanding: () => result.run({ NODE_OPTIONS: `--import=${preload}` }) };
 }
 
-test('exports unestablished library landing pages without superseded navigation or support content', async (t) => {
+test('exports unestablished library landing pages after authored content without invented support content', async (t) => {
   const { root, exportLanding } = await landingFixture(t);
   await exportLanding();
   const landing = await readFile(path.join(root, '.generated-markdown/spatial-core/index.md'), 'utf8');
   assert.match(landing, /The roadmap for this library has not been established yet\./);
   assert.match(landing, /\[v1\]\(v1\/index\.md\)/);
   assert.match(landing, /\[v2\]\(v2\/index\.md\)/);
-  assert.doesNotMatch(landing, /Library summary|Requirements|Get started|composer require|Release timeline|Branch support/);
+  assert.ok(landing.indexOf('Library summary') < landing.indexOf('## Requirements'));
+  assert.ok(landing.indexOf('## Requirements') < landing.indexOf('The roadmap for this library'));
+  assert.doesNotMatch(landing, /Get started|composer require|Release timeline|Branch support/);
   const version = await readFile(path.join(root, '.generated-markdown/spatial-core/v1/index.md'), 'utf8');
   assert.match(version, /View the library roadmap\]\(\.\.\/index\.md\)/);
 });