chore(examples): conform web UI demo to main's API surface

[thewrz]

Why

The web UI demo (merged frontend-only in #225) was built against the mockup island's richer API. Now that GET /libraries (#227) and GET /projects (#229) are on main, the demo's bootstrap works again — but it still called endpoints main doesn't have (library writes, project settings/sources, coordination/required-sections, hard delete). This conforms the demo to main's real surface and restores the linkage web.

What (examples-only)

• features.js capability map — each panel checks its flag and degrades to a clear "not available in this build" state instead of 404ing. libraries/projectsList on (landed); the rest off, flipped on as future endpoints land.
• Repoint getSpecTree → GET /specs/:id (the single-spec read already returns the tree) and drop the explicit deleteReference call — refs are derived from paragraph text, so the paragraph PATCH re-derives them.
• Restore the reference-web arcs by fetching project-scoped outbound references (GET /projects/:id/specs/:specId/references, ADR-024) per loaded spec — the single-spec read no longer bundles them.

Testing

• End-to-end Playwright smoke against main: clean boot, default project auto-created, every bootstrap call 200/201, 0 console errors/404s, gated endpoints never hit
• node --check on every edited JS file; NUL-scanned
• Manual: drop a .SEC/DOCX → board populates, arcs draw

Note: examples/ is outside the linted/test surface, so there's no unit suite here — verification is node --check + the live Playwright run.

🤖 Co-authored by Claude Opus 4.8. Closes #230.

Summary by CodeRabbit

• New Features

  • Added API feature-gating system to conditionally enable/disable operations (project settings, coordination reports, library writes, spec deletion, paragraph deletion, and more).

• Refactor

  • Updated reference data loading mechanism for improved server-side management.
  • Modified paragraph editing to rely on server-side reference derivation instead of explicit client-side deletions.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new features.js file exporting API_FEATURES boolean flags for optional API capabilities. Rewrites getSpecTree to call GET /specs/:id instead of /tree, adds getOutboundReferences for project-scoped reference fetching, introduces a loadSpecReferences helper, and gates every unsupported mutation in app.js behind the corresponding feature flag.

Changes

Web UI Demo API Conformance

Layer / File(s)	Summary
API_FEATURES capability map examples/web_ui_demo/js/features.js, examples/web_ui_demo/js/app.js	Creates features.js exporting API_FEATURES with boolean flags for each optional capability; imports it into app.js.
getSpecTree repoint and getOutboundReferences examples/web_ui_demo/js/api.js, examples/web_ui_demo/js/app.js	Rewrites getSpecTree to call GET /specs/:id and return { tree, references: [] }; adds getOutboundReferences fetching project-scoped references; extends app.js API imports.
loadSpecReferences, reloadSpec, and addSpec wiring examples/web_ui_demo/js/app.js	Introduces loadSpecReferences helper that calls getOutboundReferences and populates references on each spec in the in-memory map; wires it into reloadSpec and addSpec.
Feature-gating guards across UI mutations examples/web_ui_demo/js/app.js	Adds early-return/warning guards behind API_FEATURES flags for project rename, settings save, coordination refresh, TOC save, project-source sync, library writes, spec deletion, and paragraph deletion.
Remove explicit citation-reference deletion in commitTextEdit examples/web_ui_demo/js/app.js	Removes per-reference deletion calls from commitTextEdit, relying on server-side reference re-derivation from updateParagraph.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• wrzonance/SpecR#158: The repointed getSpecTree now calls GET /specs/:id expecting a tree field, which depends on the backend GET /specs/:id read path introduced in this PR.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.83% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: conforming the web UI demo to match the API surface available on the main branch.
Linked Issues check	✅ Passed	The PR fully implements all three stated objectives from issue #230: adding features.js capability map, consolidating getSpecTree to GET /specs/:id, and restoring reference-web via project-scoped references.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to conforming the demo to main's API surface; no unrelated modifications are present in the changeset.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/demo-conform

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[thewrz]

Worked with a docx file, but not a sec file. This is okay for this phase of development.