From 5c48f4ba777a51cf162d3433a6a4f43eb1ffefca Mon Sep 17 00:00:00 2001
From: "shoney.arickathil" <shoney.john@outlook.com>
Date: Mon, 24 Aug 2026 00:15:38 +0200
Subject: [PATCH] feat(shop): 37 target = in-class raw template literals
 (developer form)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- separate view.html files dropped; every render() now carries its
  '-- 37 target:' literal above the hand-lowered body — the pair is
  the DX referendum in one file
- story 37 re-pointed: raw multi-line literal + {{ }} auto-escaped
  typed holes + {!! !!} raw slots; structural control stays if/for;
  w:if/w:for and .html files demoted to later; forks revised
- rebuild verified on untouched toolchain

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/examples/shop/README.md                  | 26 +++++-----
 docs/examples/shop/layout/app.html            | 20 --------
 docs/examples/shop/layout/app.wo              | 14 +++++
 docs/examples/shop/layout/footer.html         |  7 ---
 docs/examples/shop/layout/footer.wo           |  2 +
 docs/examples/shop/layout/header.html         | 11 ----
 docs/examples/shop/layout/header.wo           |  6 +++
 docs/examples/shop/orders/view.html           | 28 ----------
 docs/examples/shop/orders/view.wo             | 30 ++++++++++-
 docs/examples/shop/product_list/view.html     | 20 --------
 docs/examples/shop/product_list/view.wo       | 26 ++++++++--
 docs/examples/shop/product_page/view.html     | 18 -------
 docs/examples/shop/product_page/view.wo       | 18 +++++++
 .../refine/37-wo-html-components.md           | 51 ++++++++++---------
 14 files changed, 130 insertions(+), 147 deletions(-)
 delete mode 100644 docs/examples/shop/layout/app.html
 delete mode 100644 docs/examples/shop/layout/footer.html
 delete mode 100644 docs/examples/shop/layout/header.html
 delete mode 100644 docs/examples/shop/orders/view.html
 delete mode 100644 docs/examples/shop/product_list/view.html
 delete mode 100644 docs/examples/shop/product_page/view.html

diff --git a/docs/examples/shop/README.md b/docs/examples/shop/README.md
index 4af0cba..5b57161 100644
--- a/docs/examples/shop/README.md
+++ b/docs/examples/shop/README.md
@@ -29,7 +29,7 @@ it and restart: the orders are still there (WAL replay).
 | `product_page/`, `orders/` | one view module per feature + its root controller file | feature folders |
 | `static_files/controller.wo` | `/assets/*` from disk, traversal-safe, typed | `angular.json` assets |
 | `assets/style.css` | ONE real stylesheet, sectioned per feature | the `.scss` files |
-| `*/view.html`, `layout/*.html` | STORY 37's TARGET — markup-first templates ({{ }} auto-escaped, w:if/w:for, {!! !!} slots) that woc will COMPILE against the view classes; inert today | `.component.html` / Vue `<template>` |
+| the `-- 37 target:` block above each `render()` | STORY 37's TARGET — an in-class raw template literal ({{ }} auto-escaped + type-checked, {!! !!} raw slots) replacing the hand-built body below it | Vue `<template>` (in-SFC) |
 | `main.wo` | bootstrap: seed, routes, serve — nothing else | `app-routing.module.ts` + `main.ts` |
 
 Separation is compiler-enforced where the language allows it today:
@@ -39,13 +39,16 @@ sit in the root module beside `types.wo`, because of gap #1 below.
 
 ## What is deliberately different (doctrine)
 
-- **Templates compile or they don't exist (story 37).** The `.html`
-  files here are the TARGET: when 37 lands, `woc` compiles each against
-  its view class (typo'd field = compile error) and the hand-written
-  `render()` methods in `view.wo` disappear. Until then the `.wo` files
-  are the running hand-lowering of exactly that markup, and NO template
-  engine runs at request time — ever. Styles stay a real CSS file,
-  served statically (there is no scss preprocessor).
+- **Templates compile or they don't exist (story 37).** The target is
+  an IN-CLASS raw template literal: `render()` returns one multi-line
+  literal whose `{{ expr }}` holes are auto-escaped, compile-time-
+  checked interpolations (typo'd field = compile error); `{!! !!}` is
+  the raw slot for prebuilt fragments; structural control stays the
+  language's `if`/`for` composing literals. Every `render()` here
+  carries that target as the `-- 37 target:` comment above it — the
+  body below is today's hand-lowering. NO template engine runs at
+  request time — ever. Styles stay a real CSS file, served statically
+  (there is no scss preprocessor).
 - **No closures, no DI.** A view is a class with fields + `render()`;
   a controller is a class satisfying `Handler`. Capture = a field.
 - **No sessions/cart yet.** Buying is per-product (qty → order). A cart
@@ -68,8 +71,7 @@ sit in the root module beside `types.wo`, because of gap #1 below.
 1. `types.wo` — the entire persistence layer is 20 lines.
 2. `orders.controller.wo` — the whole buying flow (validate, stock
    check, decrement, durable insert, render) with no framework magic.
-3. `product_list/view.html` NEXT TO `product_list/view.wo` — the
-   template 37 will compile vs today's hand-lowering. The pair is the
-   referendum: the `.html` is what writing a view will feel like, the
-   `.wo` is what it costs today.
+3. `orders/view.wo` — each `-- 37 target:` literal vs the hand-built
+   body under it. The pair is the referendum: the literal is what
+   writing a view will feel like, the body is what it costs today.
 4. `main.wo` — the app at a glance: five routes, one middleware, serve.
diff --git a/docs/examples/shop/layout/app.html b/docs/examples/shop/layout/app.html
deleted file mode 100644
index 933862d..0000000
--- a/docs/examples/shop/layout/app.html
+++ /dev/null
@@ -1,20 +0,0 @@
-<!-- layout/app.html — STORY 37's TARGET for the app shell: the document
-     every page shares. {!! !!} slots take prebuilt fragments (header,
-     footer, the page content); app.wo is the hand-lowered equivalent. -->
-
-<template w:component="AppShell">
-  <!doctype html>
-  <html>
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width,initial-scale=1">
-    <title>{{ self.title }}</title>
-    <link rel="stylesheet" href="/assets/style.css">
-  </head>
-  <body>
-    {!! self.header !!}
-    <main class="site-main">{!! self.content !!}</main>
-    {!! self.footer !!}
-  </body>
-  </html>
-</template>
diff --git a/docs/examples/shop/layout/app.wo b/docs/examples/shop/layout/app.wo
index 7e2905b..e5c33c5 100644
--- a/docs/examples/shop/layout/app.wo
+++ b/docs/examples/shop/layout/app.wo
@@ -6,6 +6,20 @@
 use framework/http
 use html
 
+-- 37 target:
+--   return `
+--     <!doctype html><html>
+--     <head>
+--       <meta charset="utf-8">
+--       <meta name="viewport" content="width=device-width,initial-scale=1">
+--       <title>{{ title }}</title>
+--       <link rel="stylesheet" href="/assets/style.css">
+--     </head>
+--     <body>
+--       {!! header() !!}
+--       <main class="site-main">{!! content !!}</main>
+--       {!! footer() !!}
+--     </body></html>`;
 pub fn app_shell(title: Text, content: Text) -> Text {
   let d = "<!doctype html><html><head><meta charset=\"utf-8\">";
   d = d .. "<meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">";
diff --git a/docs/examples/shop/layout/footer.html b/docs/examples/shop/layout/footer.html
deleted file mode 100644
index 7344101..0000000
--- a/docs/examples/shop/layout/footer.html
+++ /dev/null
@@ -1,7 +0,0 @@
-<!-- layout/footer.html — STORY 37's TARGET; footer.wo hand-lowers it. -->
-
-<template w:component="Footer">
-  <footer class="site-footer">
-    writeonce shop — one binary: server, database, these pages.
-  </footer>
-</template>
diff --git a/docs/examples/shop/layout/footer.wo b/docs/examples/shop/layout/footer.wo
index e840075..03a9222 100644
--- a/docs/examples/shop/layout/footer.wo
+++ b/docs/examples/shop/layout/footer.wo
@@ -1,6 +1,8 @@
 -- layout/footer.wo — the footer fragment (footer.html's analog).
 use html
 
+-- 37 target:
+--   return `<footer class="site-footer">writeonce shop — one binary: server, database, these pages.</footer>`;
 pub fn footer() -> Text {
   return el("footer", "site-footer", "writeonce shop — one binary: server, database, these pages.");
 }
diff --git a/docs/examples/shop/layout/header.html b/docs/examples/shop/layout/header.html
deleted file mode 100644
index 8413879..0000000
--- a/docs/examples/shop/layout/header.html
+++ /dev/null
@@ -1,11 +0,0 @@
-<!-- layout/header.html — STORY 37's TARGET; header.wo hand-lowers it. -->
-
-<template w:component="Header">
-  <header class="site-header">
-    <a href="/" class="brand">writeonce shop</a>
-    <nav class="site-nav">
-      <a href="/">Products</a>
-      <a href="/orders">Orders</a>
-    </nav>
-  </header>
-</template>
diff --git a/docs/examples/shop/layout/header.wo b/docs/examples/shop/layout/header.wo
index 3426d4a..6f15a94 100644
--- a/docs/examples/shop/layout/header.wo
+++ b/docs/examples/shop/layout/header.wo
@@ -1,6 +1,12 @@
 -- layout/header.wo — the header fragment (header.html's analog).
 use html
 
+-- 37 target:
+--   return `
+--     <header class="site-header">
+--       <a href="/" class="brand">writeonce shop</a>
+--       <nav class="site-nav"><a href="/">Products</a> <a href="/orders">Orders</a></nav>
+--     </header>`;
 pub fn header() -> Text {
   let brand = link("/", "brand", "writeonce shop");
   let nav = link("/", "", "Products") .. link("/orders", "", "Orders");
diff --git a/docs/examples/shop/orders/view.html b/docs/examples/shop/orders/view.html
deleted file mode 100644
index 59f6f11..0000000
--- a/docs/examples/shop/orders/view.html
+++ /dev/null
@@ -1,28 +0,0 @@
-<!-- orders/view.html — STORY 37's TARGET (see product_list/view.html for
-     the convention). view.wo is the hand-lowered equivalent. -->
-
-<template w:component="OrderOk">
-  <div class="card">
-    <h1>Order placed</h1>
-    <p>{{ self.qty }} × {{ self.name }} — total € {{ self.total }}</p>
-    <p><a href="/orders">See all orders</a> · <a href="/">Keep shopping</a></p>
-  </div>
-</template>
-
-<template w:component="OrderRow">
-  <tr>
-    <td>{{ self.name }}</td>
-    <td>{{ self.qty }}</td>
-    <td>€ {{ self.total }}</td>
-    <td>{{ self.status }}</td>
-  </tr>
-</template>
-
-<template w:component="OrdersPage">
-  <h1>Orders</h1>
-  <p w:if="self.rows == ''">No orders yet — <a href="/">go buy something</a>.</p>
-  <table w:if="self.rows != ''" class="orders">
-    <tr><th>Product</th><th>Qty</th><th>Total</th><th>Status</th></tr>
-    {!! self.rows !!}
-  </table>
-</template>
diff --git a/docs/examples/shop/orders/view.wo b/docs/examples/shop/orders/view.wo
index c7f60ba..1e00bbe 100644
--- a/docs/examples/shop/orders/view.wo
+++ b/docs/examples/shop/orders/view.wo
@@ -1,4 +1,6 @@
--- orders/view.wo — the confirmation page and the orders table.
+-- orders/view.wo — the confirmation page and the orders table. The
+-- comment above each render() is the STORY-37 TARGET (raw template
+-- literal, {{ }} auto-escaped); the body is today's hand-lowering.
 use html
 
 pub class OrderOk {
@@ -6,6 +8,13 @@ pub class OrderOk {
   qty:   Int
   total: Float
 
+  -- 37 target:
+  --   return `
+  --     <div class="card">
+  --       <h1>Order placed</h1>
+  --       <p>{{ self.qty }} × {{ self.name }} — total € {{ self.total }}</p>
+  --       <p><a href="/orders">See all orders</a> · <a href="/">Keep shopping</a></p>
+  --     </div>`;
   fn render() -> Text {
     let head = el("h1", "", "Order placed");
     let what = el("p", "", "${self.qty} × ${esc(self.name)} — total € ${self.total}");
@@ -20,6 +29,14 @@ pub class OrderRow {
   total:  Float
   status: Text
 
+  -- 37 target:
+  --   return `
+  --     <tr>
+  --       <td>{{ self.name }}</td>
+  --       <td>{{ self.qty }}</td>
+  --       <td>€ {{ self.total }}</td>
+  --       <td>{{ self.status }}</td>
+  --     </tr>`;
   fn render() -> Text {
     let cells = el("td", "", esc(self.name));
     cells = cells .. el("td", "", "${self.qty}");
@@ -32,6 +49,17 @@ pub class OrderRow {
 pub class OrdersPage {
   rows: Text
 
+  -- 37 target:
+  --   if self.rows == "" {
+  --     return `<h1>Orders</h1>
+  --             <p>No orders yet — <a href="/">go buy something</a>.</p>`;
+  --   }
+  --   return `
+  --     <h1>Orders</h1>
+  --     <table class="orders">
+  --       <tr><th>Product</th><th>Qty</th><th>Total</th><th>Status</th></tr>
+  --       {!! self.rows !!}
+  --     </table>`;
   fn render() -> Text {
     let head = el("h1", "", "Orders");
     if self.rows == "" {
diff --git a/docs/examples/shop/product_list/view.html b/docs/examples/shop/product_list/view.html
deleted file mode 100644
index 1c5e777..0000000
--- a/docs/examples/shop/product_list/view.html
+++ /dev/null
@@ -1,20 +0,0 @@
-<!-- product_list/view.html — STORY 37's TARGET, not yet compiled.
-     When 37 lands, woc compiles this file against the view classes in
-     view.wo; until then view.wo's render() methods are the HAND-LOWERED
-     equivalent of exactly this markup. Notation ({{ }} auto-escaped,
-     {!! !!} raw slot, w:if / w:for) is illustrative — 37's spec settles
-     the final spelling. -->
-
-<template w:component="ProductCard">
-  <div class="card">
-    <h3><a href="/p/{{ self.sku }}">{{ self.name }}</a></h3>
-    <p class="price">€ {{ self.price }}</p>
-    <p w:if="self.stock > 0" class="stock">{{ self.stock }} in stock</p>
-    <p w:if="self.stock == 0" class="stock out">sold out</p>
-  </div>
-</template>
-
-<template w:component="ProductListPage">
-  <h1>Products</h1>
-  <div class="grid">{!! self.cards !!}</div>
-</template>
diff --git a/docs/examples/shop/product_list/view.wo b/docs/examples/shop/product_list/view.wo
index 981406d..4ed9c01 100644
--- a/docs/examples/shop/product_list/view.wo
+++ b/docs/examples/shop/product_list/view.wo
@@ -1,8 +1,11 @@
--- product_list/view.wo — the VIEW (view.html's analog). Classes with
--- `fn render() -> Text`: fields are exactly the values displayed, the
--- markup reads top to bottom. No queries here — the controller fills
--- the fields. (A future `@view` class would let a projection query fill
--- them directly; today the controller copies the fields in.)
+-- product_list/view.wo — the VIEW. Classes with `fn render() -> Text`:
+-- fields are exactly the values displayed. No queries here — the
+-- controller fills the fields.
+--
+-- Each render() carries its STORY-37 TARGET above it: a raw multi-line
+-- template literal whose {{ expr }} holes are auto-escaped, compile-
+-- time-checked interpolations (a typo'd field = compile error). The
+-- body below is today's hand-lowering of exactly that literal.
 use html
 
 pub class ProductCard {
@@ -11,6 +14,15 @@ pub class ProductCard {
   price: Float
   stock: Int
 
+  -- 37 target:
+  --   let tail = `<p class="stock">{{ self.stock }} in stock</p>`;
+  --   if self.stock == 0 { tail = `<p class="stock out">sold out</p>`; }
+  --   return `
+  --     <div class="card">
+  --       <h3><a href="/p/{{ self.sku }}">{{ self.name }}</a></h3>
+  --       <p class="price">€ {{ self.price }}</p>
+  --       {!! tail !!}
+  --     </div>`;
   fn render() -> Text {
     let h = el("h3", "", link("/p/${esc(self.sku)}", "", esc(self.name)));
     let price = el("p", "price", "€ ${self.price}");
@@ -25,6 +37,10 @@ pub class ProductCard {
 pub class ProductListPage {
   cards: Text
 
+  -- 37 target:
+  --   return `
+  --     <h1>Products</h1>
+  --     <div class="grid">{!! self.cards !!}</div>`;
   fn render() -> Text {
     let head = el("h1", "", "Products");
     let grid = el("div", "grid", self.cards);
diff --git a/docs/examples/shop/product_page/view.html b/docs/examples/shop/product_page/view.html
deleted file mode 100644
index 6bccfc9..0000000
--- a/docs/examples/shop/product_page/view.html
+++ /dev/null
@@ -1,18 +0,0 @@
-<!-- product_page/view.html — STORY 37's TARGET (see product_list/view.html
-     for the convention). view.wo is the hand-lowered equivalent. -->
-
-<template w:component="ProductPage">
-  <div class="card detail">
-    <h1>{{ self.name }}</h1>
-    <p class="price">€ {{ self.price }}</p>
-    <p class="stock">{{ self.stock }} in stock</p>
-
-    <form w:if="self.stock > 0" method="POST" action="/orders/{{ self.sku }}">
-      <label>Quantity</label>
-      <input type="text" name="qty" value="1" class="field">
-      <button type="submit" class="btn">Buy</button>
-    </form>
-    <p w:if="self.stock == 0" class="stock out">sold out</p>
-  </div>
-  <p><a href="/">← all products</a></p>
-</template>
diff --git a/docs/examples/shop/product_page/view.wo b/docs/examples/shop/product_page/view.wo
index 2acbc04..2352aef 100644
--- a/docs/examples/shop/product_page/view.wo
+++ b/docs/examples/shop/product_page/view.wo
@@ -1,4 +1,6 @@
 -- product_page/view.wo — the product detail view with the order form.
+-- The comment above render() is the STORY-37 TARGET (raw template
+-- literal, {{ }} auto-escaped); the body is today's hand-lowering.
 use html
 
 pub class ProductPage {
@@ -7,6 +9,22 @@ pub class ProductPage {
   price: Float
   stock: Int
 
+  -- 37 target:
+  --   let action = `
+  --     <form method="POST" action="/orders/{{ self.sku }}">
+  --       <label>Quantity</label>
+  --       <input type="text" name="qty" value="1" class="field">
+  --       <button type="submit" class="btn">Buy</button>
+  --     </form>`;
+  --   if self.stock == 0 { action = `<p class="stock out">sold out</p>`; }
+  --   return `
+  --     <div class="card detail">
+  --       <h1>{{ self.name }}</h1>
+  --       <p class="price">€ {{ self.price }}</p>
+  --       <p class="stock">{{ self.stock }} in stock</p>
+  --       {!! action !!}
+  --     </div>
+  --     <p><a href="/">← all products</a></p>`;
   fn render() -> Text {
     let head = el("h1", "", esc(self.name));
     let price = el("p", "price", "€ ${self.price}");
diff --git a/docs/stories/language-runtime-database/refine/37-wo-html-components.md b/docs/stories/language-runtime-database/refine/37-wo-html-components.md
index fa254cc..5832e4d 100644
--- a/docs/stories/language-runtime-database/refine/37-wo-html-components.md
+++ b/docs/stories/language-runtime-database/refine/37-wo-html-components.md
@@ -18,24 +18,27 @@ status: refine
 >
 > **REDIRECTED 2026-08-23** (developer review of the shop template
 > against a Vue SFC): render()-as-string-concatenation failed the DX
-> referendum — markup must be markup-FIRST. New direction:
-> **`view.html` template files COMPILED BY `woc` into render code** —
-> `{{ self.name }}` interpolation (auto-escaped; a raw opt-out spelling
-> for prebuilt fragments), `w:if`/`w:for` structural attributes, typed
-> against the view class's fields at compile time (a typo'd field is a
-> compile error), NO template engine at runtime — the doctrine's real
-> meaning becomes "no template interpreted at request time", not "no
-> template files". A runtime mustache-lite was considered and REJECTED:
-> reflection-free means values degrade to `map<Text, Text>` — typing
-> lost. Client-side reactivity from the Vue sample (`ref`, `@click`,
-> `v-model`) stays out under the no-JS posture; qty steppers are form
-> fields, actions are POSTs. This makes 37 a COMPILER iteration too
-> (template-to-code lowering), gated behind the standing
-> "no compiler/VM/database changes yet" directive — schedule
-> accordingly. The shop template
+> referendum — markup must be markup-FIRST. **RE-POINTED 2026-08-24**
+> (developer counter-proposal): the leaning is now **in-class raw
+> template literals**, not separate `.html` files — `render()` RETURNS
+> a raw multi-line string literal whose `{{ expr }}` holes are
+> auto-escaped, compile-time-checked interpolations in class scope (a
+> typo'd field is a compile error). Compiler surface shrinks to one
+> lexer addition (the raw literal — a general language win: multi-line
+> text without `\"` noise) plus one desugar; no file pairing, no
+> `w:component` sections. Structural control stays the language's own
+> `if`/`for` composing literals; `w:if`/`w:for` attributes and separate
+> `.html` files are DEMOTED to a later option that can layer on without
+> breaking this form. Escaping: `{{ }}` always escapes; the raw/slot
+> spelling is the one greppable door. A runtime mustache-lite stays
+> REJECTED (reflection-free means untyped `map<Text, Text>`); client-
+> side reactivity (`ref`, `@click`, `v-model`) stays out under the
+> no-JS posture — forms and POSTs instead. Still a COMPILER iteration,
+> parked behind the standing "no compiler/VM/database changes yet"
+> directive. The shop template
 > ([`docs/examples/shop`](../../../examples/shop/README.md)) is the
-> consumer: its `view.wo` classes become `view.html` + view classes,
-> and its README's recorded gaps ride along (gap #1: `pub` + `@table`
+> consumer: each `render()` body becomes one raw template literal, and
+> its README's recorded gaps ride along (gap #1: `pub` + `@table`
 > cannot combine — blocks a shared model module; gap #2: `@view`
 > projection classes).
 
@@ -115,14 +118,12 @@ detection, event bindings, SPA router) deliberately does not.
 Forks the spec must settle (REVISED 2026-08-23 for the compiled-template
 direction):
 
-1. **Template pairing** — Vue-SFC style (one `view.html` whose
-   frontmatter/`<script>` block declares the fields) vs paired files
-   (`view.html` + a `.wo` view class it compiles against). Leaning:
-   paired — the class stays ordinary `.wo`, the template is pure markup.
-2. **Directive surface** — the minimal set: `{{ expr }}` (auto-escaped),
-   a raw spelling for prebuilt fragments (slots), `w:if`, `w:for`,
-   `w:class`-style conditional classes. Anything beyond is YAGNI until a
-   sample demands it.
+1. **The raw-literal spelling** — backticks, triple quotes, or another
+   delimiter; and the raw-slot spelling inside it (`{!! !!}` vs `${}`
+   staying unescaped). One rule: `{{ }}` always escapes.
+2. **Directive surface** — v1 ships NONE (structural control is `if`/
+   `for` composing literals); `w:if`/`w:for` and separate `.html` files
+   layer on later only if a sample proves the need.
 3. **Escaping default** — `{{ }}` escapes ALWAYS (safer than today's
    caller-explicit `esc()`); the raw spelling is the only door, and it
    is greppable.