Add "when to use which" guidance for template return types

[bcomnes]

This issue was originally identified in voxpelli/voxpelli.github.com#32

Problem

The DomStack README documents all four template return types (string, object, array, async iterator) with full TypeScript examples and type annotations. However, it presents them as equal options without guidance on when to use which. Users who encounter the array or async iterator examples first may default to more complex patterns even for trivial single-file templates.

What's missing

A decision guide or comparison table that helps users choose the simplest pattern for their needs:

Return type	Sync?	Custom filename?	Multiple outputs?	Async operations?
String	Yes	No (derived from template name)	No	No
Object	Yes	Yes	No	No
Array	Yes	Yes	Yes	No
Async Iterator	No	Yes	Yes	Yes

Real-world impact

Without this guidance, templates commonly use array returns for single outputs when simpler patterns would suffice:

Template	Current return type	Simplest sufficient type
robots.txt.template.js	Array (1 element)	String
manifest.json.template.js	Array (1 element)	Object
sitemap.xml.template.js	Array (1 element)	Object
redirects.template.js	Array (N elements)	Array (correct)
feeds.template.js	Async iterator	Async iterator (correct)

Proposed solution

Add a brief "When to use which" comparison table to the existing Templates documentation section, after the four return type examples. This is a small addition — no new section needed, just a summary that ties the existing examples together.

Related

• Exporting TemplateOutputOverride, TemplateFunctionParams, and TemplateInfo types would make the documented API importable for type checking.
• The async iterator pattern is the primary way to use renderInnerPage() for multiple outputs.