Decide: VisioScripting public-API status (document or keep internal?)

[saveenr]

Decision item in Milestone E. Detail in docs/futures/docs.md under "Decide whether to document VisioScripting as a public API".

Goal

Decide: is VisioScripting (the higher-level facade between VisioAutomation and VisioPowerShell) a public API that we document for direct .NET use, or an internal layer that exists only to back the PowerShell module?

Why this matters

• If "public": needs full gitbook documentation (similar in size to Tiers 1+2+4 of the .NET-side coverage, per docs/futures/docs.md). Adds breaking-change considerations to its surface going forward.
• If "internal": no doc-writing required, and we have flexibility to refactor it freely. Should be marked as such (e.g., Internal/ namespace move, or a clear note in OVERVIEW.md).
• If "neither" (i.e., "use it if you want, but no support promise"): a third option that mirrors how a lot of community libraries handle this. Document only what's stable, mark the rest as "evolving".

Acceptance

• Decision recorded in docs/OVERVIEW.md policy section (or a new dev-docs decision file).
• If "public": follow-up issue to write the docs (similar shape to #131 and #132).
• If "internal": code follows (namespace move, headers updated, etc.) — separate follow-up.

Cross-refs

• docs/futures/docs.md "Decide whether to document VisioScripting as a public API".
• Couples to the long-term docs-location decision (#155) since that affects the cost-of-documenting calculation.

Effort

S to decide. M-L to act on if "yes, document it".

[saveenr]

Decision: hybrid public API

VisioScripting.Client and the 25-group facade are committed as the public-stable contract. Implementation-detail types stay internal-mutable.

Q1 — Public/internal line

Public-stable (documented; breaking changes treated as breaking):

• VisioScripting.Client (type, constructors, 25 group properties)
• Public method signatures on each *Commands class
• Target* types at namespace root (forced — appear in signatures)
• VisioScripting.Models.* enums and value types referenced from public signatures
• ClientContext, DefaultClientContext (subclassable for embedding)

Internal-mutable (not contract; free to change):

• *Commands classes as constructible types (already enforced via internal ctors)
• VisioScripting.Helpers/*
• VisioScripting.Loaders/* (after Q3 facade migration)
• CommandTarget, CommandTargetFlags
• Models.* types not appearing in any public signature
• Client.GetCommandTarget(flags) — implementation helper

Q2 — Enforcement

Layered, weakest-to-strongest:

1. C# internal keyword wherever the type system allows it, with [InternalsVisibleTo(...)] for VisioPowerShell and the four test projects.
2. [EditorBrowsable(EditorBrowsableState.Never)] + XML doc comments for the few types that have to stay public for signature reasons but aren't part of the contract.
3. ADR at docs/decisions/visioscripting-public-api.md capturing the rule.
4. Note in CLAUDE.md per-commit conventions section.
5. PublicAPI.Shipped.txt analyzer deferred; revisit if drift becomes a real problem.

Q3 — Boundary leaks

Two cmdlets currently bypass the facade. Both resolve via new facade methods (option a in both cases):

• VisioScripting.Loaders.*.LoadFromXml(...) → add Client.Model.LoadDirectedGraphFromXml(XDocument) and Client.Model.LoadOrgChartFromXml(XDocument). Migrate ImportVisioModel cmdlet + 2 tests in VTest.Models. Mark Loaders/ internal. Drop the unused LoadFromXml(client, string filename) overload.
• VisioScripting.Models.*Dimensions.Get_*Dimensions(...) → add Client.Page.GetPageDimensions(TargetPages) and Client.Selection.GetShapeDimensions(TargetShapes). Migrate MeasureVisioPage + MeasureVisioShape cmdlets. Mark the static factory methods internal. The data-carrier types PageDimensions / ShapeDimensions stay public — they're return values.

(Selection.GetShapeDimensions is placement-of-convenience; "should there be a dedicated ShapeCommands class?" is a larger architectural question, deferred.)

Q4 — Pre-lock cleanup

Two precondition phases; one deferred to CY27:

• Phase B — boundary-leak facade methods. Per Q3. Precondition for the lock. ~6h.
• Phase C — enforcement application. Per Q2. Precondition for the lock. ~3h.
• Phase A — dead-method removal. ~36 unused public methods + dead LayerCommands class + 4 unused OutputCommands methods + ContainerrCommands.cs filename typo. Deferred to CY27 (audience-reducing change per the project's guiding principle). Filed separately as #183.

Rationale

The usage audit found Client is the dominant consumer pattern (~76% of method usage flows through client.<Group>.<Method>). Going fully public would commit ~152 method signatures plus Helpers/, Loaders/, CommandTarget — too generous, and locks in implementation details. Going fully internal would orphan the readme's quick-start (which opens with VisioScripting.Client) and force closing #131 won't-fix despite a real C# audience. Hybrid lets the facade be public while keeping the plumbing flexible.

Open sub-question

Should the documented public surface treat the ~36 dead methods as "public, documented, candidate for CY27 removal" (honest; hints at deprecation) or "public, documented, stable" (no signal)? Decide before #131 starts.

Implications

• #131 (document VisioScripting.Client): now blocked by #182, not this one. Doc surface ≈ Client + 25 *Commands classes + Target* types + ClientContext / DefaultClientContext + the public Models.* types in signatures. After Phase B the method count is ~156 (the existing ~152 + 4 new facade methods).
• #172 (revise user-facing docs): can now confidently include VisioScripting.Client in C# narrative without disclaimers.
• #157 (long-term docs location): plan around a stable VisioScripting surface.
• #162 (PSVA Phase A scoping): cmdlet/Scripting boundary is now governed by the hybrid contract; Phase A must respect it.
• #164 (VisioCmdlet base from Cmdlet to PSCmdlet): orthogonal — doesn't touch the public Scripting surface.

Follow-ups filed

• #182 — VisioScripting public-API pre-lock cleanup (Phases B + C). CY26Q3. Blocks #131.
• #183 — VisioScripting dead-method removal (Phase A). CY27Q1.

Closing.