Duolith docs

0026. One TypeScript "script view" per page for editor intelligence

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only)
  • Planning item: none

Context

The TypeScript service must see the script block and every {expression} together, so that names from the script complete, check, hover, go to definition and rename in markup, and a list's item has the type of what it repeats over. It must not report problems in code the user did not write.

Decision

The compiler service makes one TypeScript file per page, the script view (crates/wasm/src/script_view.rs):

/// <reference path=".../duolith-environment.d.ts" />
<script block, as written>
;function __duolith_markup(): void {
  (draft);                                      // {draft}
  __duolith_on<{ readonly value: string }>((event) => ...);  // on:input={...}
  for (const post of __duolith_items(posts)) {   // <list each={posts} as="post">
    (post.caption);
  }
}
export default {} as __DuolithComponent;
  • Only the copied pieces (the script block, each expression, and a list's as name) are mapped back to the page; diagnostics in generated text are never shown.
  • A list's item is in scope for its children and its own attributes (so a key can use it).
  • __duolith_on gives each event's handler the type the event receives in spec/language/elements.yaml (decision 0027). A list with index="i" iterates __duolith_entries, so i is a number.
  • Each page file is a TypeScript module with a default export, so import Card from "../components/Card.duo" resolves (decision 0015).
  • If @duolith/client is not installed, fallback declarations of state, derived, effect and props are used.

Alternatives considered

OptionWhy not
One virtual file per expressionExpressions could not see each other's scope, and the script would be type-checked many times
Inline expressions at top level after the scriptA list item would need a top-level declaration, colliding with script names

Consequences

The helpers are declared in packages/language-server/types/duolith-environment.d.ts; the event types come from the language definition, so a new event needs no change here.