# Authoring reference

## File shape

Begin each file with one bodyless typed component signature:

```sando
<?sando go
package views
func Card(title string, body sando.Component)
?>
<article>
  <h2><?= title ?></h2>
  <?~ body ?>
</article>
```

Use `<? … ?>` for Go statements, `<?= … ?>` for contextually escaped output,
`<?~ … ?>` for component composition, and `<?# … ?>` for template comments.
Statements and components belong at HTML content boundaries. Components may
nest through ordinary typed function calls; there is no inheritance DSL.

## Contexts

Hime-san assigns HTML text, quoted attribute, URL, RCDATA, script, or style
contexts before code generation and rejects ambiguous markup construction.
Script and style expressions require explicitly trusted runtime values. RCDATA
always escapes, including trusted wrappers. URL output rejects disallowed or
ambiguous schemes before writing.

Do not dynamically construct element names, attribute names, event handlers,
unquoted attributes, `srcset`-style URL lists, `srcdoc`, or foreign content.

## Trust

`Trust*` constructors and handwritten `sando.Component` implementations can
emit bytes that the compiler cannot prove safe. Treat them like filesystem or
network capabilities: narrow, document, review, and test each boundary.

Generated compiler diagnostics preserve one-based byte columns. The language
server translates only its editor-facing boundary to UTF-16 positions.