@transclude/core 0.1.1 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Joe Dakroub
+Copyright (c) 2026 Atelier Dakroub
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,11 +1,28 @@
-# transclude
+<h1 align="center">transclude</h1>
+
+<p align="center">An HTML-first server-side web framework.</p>
+
+<p align="center">
+  <a href="https://github.com/transclude-dev/transclude/actions/workflows/ci.yml"
+    ><img alt="CI" src="https://github.com/transclude-dev/transclude/actions/workflows/ci.yml/badge.svg"
+  /></a>
+  <a href="https://www.npmjs.com/package/@transclude/core"
+    ><img alt="npm" src="https://img.shields.io/npm/v/%40transclude%2Fcore?color=0b7285"
+  /></a>
+  <a href="https://transclude.dev/docs/runtimes"
+    ><img alt="node" src="https://img.shields.io/node/v/%40transclude%2Fcore?color=0b7285"
+  /></a>
+  <a href="https://github.com/transclude-dev/transclude/blob/main/LICENSE"
+    ><img alt="MIT" src="https://img.shields.io/npm/l/%40transclude%2Fcore?color=0b7285"
+  /></a>
+</p>
 
 HTML is the product. A page is an `.html` file, the directory tree is the route
 table, and any fragment of a page is a URL of its own. Nothing has to run in the
 browser for the page to be correct.
 
-The same app runs on Node, Bun, Deno and workerd, and ships no client JavaScript
-by default.
+The same app runs on Node, Bun, Deno and workerd, the runtime behind
+Cloudflare Workers, and ships no client JavaScript by default.
 
 **[transclude.dev](https://transclude.dev)** has the documentation.
 
@@ -52,7 +69,7 @@ so a swap cannot drift from the page it replaces part of.
 
 ## What is in it
 
-- **Pages and endpoints.** An `.html` file answers GET; its `POST`, `PUT`,
+- **Pages and endpoints.** An `.html` file responds to GET; its `POST`, `PUT`,
   `PATCH` and `DELETE` exports answer the rest, so a plain `<form method="post">`
   works. A `.js` file in the same tree returns a `Response`.
 - **Fragments.** Mark an element `fragment` and it has a URL of its own. htmx,
@@ -74,9 +91,10 @@ so a swap cannot drift from the page it replaces part of.
 
 - **No client-side router, and no swapper.** Every link is a document request
   unless you bring something that swaps. That is a decision, not a gap.
-- **No streaming.** The body is buffered so it can be hashed, which is what buys
-  the ETag. A `Link: rel=preload` goes out first, so a proxy can turn it into a
-  103 while the page is still being made.
+- **A page does not stream.** Its body is buffered so it can be hashed, which is
+  what buys the ETag. A `Link: rel=preload` goes out first, so a proxy can turn
+  it into a 103 while the page is still being made. An endpoint returns a
+  `Response` you build, so it can answer with a `ReadableStream` and stay open.
 - **No session store and no database opinion.** Signed cookies are the building
   block.
 - **No byte ranges on workerd.** A Range request gets 200 rather than 206.
@@ -96,26 +114,59 @@ so a swap cannot drift from the page it replaces part of.
 ```sh
 npm install
 npm test              # the framework's own, and they need no app
-npm run test:examples # the demo's, against a build
-npm run showcase      # the demo on http://localhost:1961
+npm run test:examples # the examples', against a build
+npm run showcase      # the showcase on http://localhost:1961
+npm run todomvc       # TodoMVC on http://localhost:1962
+npm run blog          # a prerendered blog on http://localhost:1963
+npm run search        # search over a fragment on http://localhost:1964
+npm run htmx          # the same, driven by htmx, on http://localhost:1965
+npm run includes      # transclusion on http://localhost:1966
+npm run auth          # a guarded section on http://localhost:1967
+npm run live          # server-sent events on http://localhost:1968
+npm run elements      # light and shadow elements on http://localhost:1969
 npm run check:src     # type-check the framework itself
 ```
 
-`examples/showcase` is an app built against this package the same way any other
-project would be. It is where the browser checks live, because those need an app
-to run against, and it is what the four runtimes are checked with. `docs/` is the
-site at transclude.dev, and is itself built with the framework.
+`examples/` holds apps built against this package the same way any other project
+would be. `todomvc` is TodoMVC with forms and no client JavaScript, `blog` is a
+prerendered site with a sitemap and a feed, `search` swaps a fragment into a
+page that works without it, `htmx` does the same with htmx and the
+`HX-Target` header, `includes` shows transclusion from three sources,
+`auth` guards a section with a layout and a signed cookie, `live` pushes
+updates over server-sent events, `elements` puts a light and a shadow element
+side by side, and `showcase` uses every feature and is where the
+browser checks live, because those need an app to run against. `www/` is the site at transclude.dev: a landing page, the
+documentation under `/docs`, and itself built with the framework.
 
 ### Trying the CLI against this checkout
 
 ```sh
-npm link                                  # once, puts create-transclude on PATH
+cd create && npm link && cd ..            # once, puts create-transclude on PATH
 create-transclude my-app --template blank --link
 ```
 
 `--link` points the new project at this checkout rather than the registry, which
 is what you want while changing the framework: an edit here is an edit there.
 
+## Working with an AI agent
+
+`skills/transclude/` is an [Agent Skill](https://agentskills.io): the framework's
+conventions, its API and the mistakes it refuses, in the format Claude Code,
+Cursor, Copilot and others read. It ships with the package, so an installed
+project has it at `node_modules/@transclude/core/skills/transclude/`.
+
+Every HTML example in it is compiled by the real compiler in `npm test`. A skill
+is documentation an agent acts on without a human reading it first, so an
+example that stops compiling is worse than a missing one.
+
+## Contributing
+
+[CONTRIBUTING.md](CONTRIBUTING.md) covers the layout, the tests and the writing
+style. Everyone taking part agrees to the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+Security problems go to admin@dakroub.co, not to a public issue.
+
 ## License
 
 MIT

package/bin/build.js

@@ -16,7 +16,7 @@ import { pathToFileURL } from 'node:url';
 import { build } from 'vite';
 import transclude from '../src/plugin.js';
 import { loadProject } from '../src/project.js';
-import { absoluteFrom, renderRoute, responseOf } from '../src/document.js';
+import { absoluteFrom, renderRoute, responseOf, urlFor } from '../src/document.js';
 import { feed, feedPath } from '../src/feed.js';
 import { includeContext } from '../src/include.js';
 import { nodeLookup } from '../src/lookup.js';
@@ -111,9 +111,15 @@ await build({
   },
 });
 
+// A worker entry imports this bundle, and an editor set to check the app's JS
+// then checks a file nobody wrote. Twenty errors in the showcase, all of them
+// about generated code. The banner is what keeps it out of that program.
+const entry = path.join(dist, 'server/entry.js');
+fs.writeFileSync(entry, `// @ts-nocheck\n${fs.readFileSync(entry, 'utf8')}`);
+
 // ---- prerender ------------------------------------------------------------
 
-const { pages } = await import(pathToFileURL(path.join(dist, 'server/entry.js')).href);
+const { pages } = await import(pathToFileURL(entry).href);
 
 /**
  * A static route has one URL. A dynamic route has as many as its `paths` export
@@ -134,7 +140,7 @@ async function urlsFor(route) {
 
   const listed = (await paths()) ?? [];
   return listed.map((params) => ({
-    url: route.pattern.replace(/:(\w+)(\{[^}]*\})?/g, (_, name) => String(params[name] ?? '')),
+    url: urlFor(route, params),
     params,
   }));
 }
@@ -316,8 +322,20 @@ const publicSrc = config.publicDir
 const publicOut = path.join(dist, 'public');
 let publicFiles = 0;
 
+/**
+ * What an operating system leaves in a directory, which nobody put there.
+ *
+ * These were copied into the build and served: `/.DS_Store` answered 200 on the
+ * docs site and lists every file beside it. Dotfiles are not skipped wholesale,
+ * because `.well-known` is a directory people mean to publish.
+ */
+const JUNK = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini']);
+
 if (publicSrc && fs.existsSync(publicSrc)) {
-  fs.cpSync(publicSrc, publicOut, { recursive: true });
+  fs.cpSync(publicSrc, publicOut, {
+    recursive: true,
+    filter: (from) => !JUNK.has(path.basename(from)),
+  });
   publicFiles = countFiles(publicOut);
 }
 

package/bin/check.js

@@ -23,7 +23,22 @@ if (!fs.existsSync(types) || fs.readFileSync(types, 'utf8') !== next) {
 
 // Nothing downstream reads this file, so nothing else would notice it being
 // wrong. Parse what we just wrote, or a bad identifier ships silently.
-const emitted = ts.createProgram([types], { noEmit: true, skipLibCheck: true });
+//
+// `skipLibCheck` has to be off, and it was on. This is a .d.ts, which is the one
+// kind of file that flag skips, so the guard checked nothing at all: every
+// project shipped a file naming `__Cookies` and declaring it nowhere. An editor
+// missed it too, because a jsconfig.json implies the same flag.
+//
+// `types: []` keeps it to this file: whatever `@types` a project happens to have
+// installed is not what is being checked here, and one of them failing to
+// resolve its own dependency would read as our file being broken.
+const emitted = ts.createProgram([types], {
+  noEmit: true,
+  skipLibCheck: false,
+  types: [],
+  target: ts.ScriptTarget.ESNext,
+  lib: ['lib.esnext.d.ts', 'lib.dom.d.ts'],
+});
 const broken = [
   ...emitted.getSyntacticDiagnostics(),
   ...emitted.getSemanticDiagnostics(),
@@ -63,16 +78,23 @@ for (const file of files) {
     const text = lines[line - 1] ?? '';
     const trimmed = text.replace(/^\s+/, '');
     const shift = text.length - trimmed.length;
+    // The caret line is drawn under the trimmed source, so the column moves left
+    // by however much indentation was cut. A run is capped so one long span does
+    // not wrap the terminal.
+    const pad = ' '.repeat(Math.max(0, column - shift));
+    const run = '~'.repeat(Math.max(1, Math.min(diagnostic.length, 60)));
+
     console.log(`\n    ${trimmed}`);
-    console.log(`    ${' '.repeat(Math.max(0, column - shift))}${'~'.repeat(Math.max(1, Math.min(diagnostic.length, 60)))}`);
+    console.log(`    ${pad}${run}`);
   }
 }
 
-const total = errors + warnings;
-console.log(
-  total
-    ? `\n${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'} in ${files.length} files`
-    : `\nNo type errors in ${files.length} files.`,
-);
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+
+if (errors + warnings) {
+  console.log(`\n${plural(errors, 'error')}, ${plural(warnings, 'warning')} in ${files.length} files`);
+} else {
+  console.log(`\nNo type errors in ${files.length} files.`);
+}
 
 process.exitCode = errors ? 1 : 0;

package/bin/dev.js

@@ -19,7 +19,7 @@ import {
   runAction,
   withEnvelope,
 } from '../src/document.js';
-import { clientEntryUrl, pageModuleId } from '../src/plugin.js';
+import transclude, { clientEntryUrl, pageModuleId } from '../src/plugin.js';
 import { resolveRoutesDir, scanRoutes } from '../src/routes.js';
 import { baseApp, endpointMethods, runEndpoint, SERVER_FILE } from '../src/server.js';
 import { randomBytes } from 'node:crypto';
@@ -71,6 +71,11 @@ const server = http.createServer();
 const vite = await createViteServer({
   root,
   appType: 'custom',
+  // Passed here rather than left to the project's own `vite.config.js`, which is
+  // where dev used to get it. A project needs no Vite config at all, and the one
+  // built here is the one `loadProject` filled in, so dev compiles against the
+  // same config the build does. `configResolved` ignores a second registration.
+  plugins: [transclude(config)],
   server: { middlewareMode: true, hmr: { server } },
   // Vite would serve these itself, ahead of Hono, and production would serve
   // them a different way, which is how dev and production come to disagree. One
@@ -229,7 +234,10 @@ async function loadMiddleware() {
   if (!fs.existsSync(serverFile)) return null;
 
   const url = `/${config.appDir}/${SERVER_FILE}`;
-  const node = await vite.moduleGraph.getModuleByUrl(url, true);
+  // Vite's second argument is `ssr`. This module is only ever loaded through
+  // `ssrLoadModule`, so the SSR graph is the one holding it.
+  const ssr = true;
+  const node = await vite.moduleGraph.getModuleByUrl(url, ssr);
   if (node) vite.moduleGraph.invalidateModule(node);
 
   const mod = await vite.ssrLoadModule(url);

package/bin/release.js

@@ -85,15 +85,30 @@ function setVersion(version) {
 
 /** Everything, in the order that fails cheapest first. */
 function verify() {
+  // Read rather than listed, so an example added to the repository is covered by
+  // the next release without anyone remembering this file.
+  const examples = fs
+    .readdirSync(path.join(root, 'examples'), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(root, 'examples', entry.name, 'package.json')))
+    .map((entry) => entry.name)
+    .sort();
+
   const steps = [
     // `check:src` is not here. It exits non-zero on any diagnostic, and most of
     // what it reports is a pattern TypeScript cannot model rather than a defect.
     // The part that is a gate is a test, and `npm test` runs it.
     ['the framework', 'npm', ['test']],
-    ['the demo', 'npm', ['run', 'test:examples']],
-    ['the docs', 'npm', ['test', '--prefix', 'docs']],
-    ['the docs types', 'npm', ['run', 'check', '--prefix', 'docs']],
-    ['the docs build', 'npm', ['run', 'build', '--prefix', 'docs']],
+
+    // Built before tested, and that order is the gate rather than a nicety:
+    // every example's tests ask the built app for URLs and skip when there is
+    // nothing to ask. Without this a release could pass with all of them
+    // skipped, which is a green tick over nothing.
+    ...examples.map((name) => [`${name}, built`, 'npm', ['run', 'build', '--prefix', `examples/${name}`]]),
+    ['the examples', 'npm', ['run', 'test:examples']],
+
+    ['the docs types', 'npm', ['run', 'check', '--prefix', 'www']],
+    ['the docs build', 'npm', ['run', 'build', '--prefix', 'www']],
+    ['the docs', 'npm', ['test', '--prefix', 'www']],
   ];
 
   for (const [what, command, args] of steps) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "An HTML-first server framework. A page is an .html file, the directory tree is the route table, and any fragment of a page is a URL of its own. Runs on Node, Bun, Deno and workerd, and ships no client JavaScript by default.",
   "keywords": [
     "html",
@@ -52,14 +52,23 @@
     "LICENSE",
     "bin",
     "editor",
+    "skills",
     "src"
   ],
   "scripts": {
     "test": "node --test \"test/**/*.test.js\"",
-    "test:examples": "npm test --prefix examples/showcase",
-    "test:docs": "npm test --prefix docs",
+    "test:examples": "npm test --prefix examples/showcase && npm test --prefix examples/todomvc && npm test --prefix examples/blog && npm test --prefix examples/search && npm test --prefix examples/htmx && npm test --prefix examples/includes && npm test --prefix examples/auth && npm test --prefix examples/live && npm test --prefix examples/elements",
+    "test:www": "npm test --prefix www",
     "showcase": "npm run dev --prefix examples/showcase",
-    "docs": "npm run dev --prefix docs",
+    "todomvc": "npm run dev --prefix examples/todomvc",
+    "blog": "npm run dev --prefix examples/blog",
+    "search": "npm run dev --prefix examples/search",
+    "htmx": "npm run dev --prefix examples/htmx",
+    "includes": "npm run dev --prefix examples/includes",
+    "auth": "npm run dev --prefix examples/auth",
+    "live": "npm run dev --prefix examples/live",
+    "elements": "npm run dev --prefix examples/elements",
+    "www": "npm run dev --prefix www",
     "check:src": "tsc -p tsconfig.src.json",
     "release": "node bin/release.js"
   },

package/skills/transclude/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: transclude
+description: Build web apps with the transclude framework (@transclude/core), an HTML-first server-side framework on Hono. Use when working in a project that has a transclude.config.js, when writing .html pages, layouts or custom elements under app/routes/ and app/elements/, or when the user mentions transclude, fragments, transclusion, hypermedia pages, or server-rendered HTML with no client bundle.
+license: MIT
+metadata:
+  homepage: https://transclude.dev
+  package: "@transclude/core"
+---
+
+# transclude
+
+HTML is the product. A page is an `.html` file, the server renders it, and what
+arrives is markup a browser already knows how to display. Nothing has to run in
+the browser for the page to be correct.
+
+The directory tree is the route table. The same app runs on Node, Bun, Deno and
+workerd.
+
+## Start a project
+
+```sh
+npm create @transclude my-app
+cd my-app
+npm install
+npm run dev
+```
+
+## Where files go
+
+```
+app/
+  routes/          # .html is a page, .js is an endpoint
+    index.html     # /
+    notes.html     # /notes
+    notes/[id].html    # /notes/:id
+    _layout.html   # wraps every route beside and below it
+    api/people.js  # /api/people
+    api/_shared.js # not a route, the _ prefix says so
+  elements/        # every custom element, one file each
+    note-card.html # <note-card>, the name needs a dash
+  public/          # copied to the site root as-is
+transclude.config.js
+```
+
+## A page
+
+```html
+<script server>
+  import { notes } from '../data/notes.js';
+
+  export default async ({ url }) => {
+    const q = new URL(url).searchParams.get('q') ?? '';
+    return { q, notes: notes.filter((n) => n.text.includes(q)) };
+  };
+</script>
+
+<title>Notes</title>
+
+<h1>Notes</h1>
+
+<div id="list" fragment>
+  <p if="!notes.length">Nothing yet.</p>
+  <ul else>
+    <li each="note of notes">${note.text}</li>
+  </ul>
+</div>
+```
+
+The `<script server>` default export is the loader. It runs on the server and
+returns the data the markup reads. Every name in `${…}` is a field of that data.
+
+### Directives
+
+| | |
+| --- | --- |
+| `${expr}` | interpolation, escaped |
+| `if="expr"` | render this element only when true |
+| `else` | pairs with the `if` above it |
+| `each="item of items"` | repeat the element |
+| `key="expr"` | identity for a repeated element |
+| `fragment` | this element has its own URL, see references/fragments.md |
+| `slot="name"` | fill a named slot |
+
+`html(value)` renders markup without escaping. It is a claim that the markup is
+yours. It sanitizes nothing.
+
+Globals available in an expression: `html`, `json`, `Math`, `JSON`, `String`,
+`Number`, `Boolean`, `Array`, `Object`, `Date`, `isNaN`, `parseInt`,
+`parseFloat`, `undefined`, `NaN`, `Infinity`. Every other name is data.
+
+### The loader context
+
+`ctx` carries `url`, `request`, `params`, `cookies`, `fragment`, `response` and
+`absolute()`. Returning a `Response` from a loader answers the request and skips
+the render, which is how a layout does a login redirect.
+
+## Forms and actions
+
+A page responds to GET with its loader. Other verbs are named exports on the same
+file.
+
+```html
+<script server>
+  import { notes } from '../data/notes.js';
+
+  export default async () => ({ notes: notes.all() });
+
+  export const POST = async ({ request }) => {
+    const form = await request.formData();
+    notes.add(String(form.get('text')));
+  };
+</script>
+
+<form method="post">
+  <input name="text" required />
+  <button>Add</button>
+</form>
+
+<ul id="list" fragment>
+  <li each="note of notes">${note.text}</li>
+</ul>
+```
+
+The action runs, then the loader renders what it left behind. `POST`, `PUT`,
+`PATCH` and `DELETE` are the verbs. Return nothing to re-render, or return a
+`Response` to redirect.
+
+## Endpoints
+
+A `.js` file in `routes/` returns a `Response`.
+
+```js
+// app/routes/api/people.js
+import { people } from '../../data/people.js';
+
+export const GET = (ctx) => Response.json(people);
+
+export const POST = async ({ request }) => {
+  const body = await request.json();
+  people.push(body);
+  return Response.json(body, { status: 201 });
+};
+```
+
+## Layouts
+
+`_layout.html` wraps every route in its directory and below. The page renders
+into `<slot>`. Layouts nest, and each one loads its own data.
+
+```html
+<script server>
+  export default async () => ({ year: 2026 });
+</script>
+
+<header><a href="/">Home</a></header>
+<main><slot></slot></main>
+<footer>${year}</footer>
+```
+
+## Commands
+
+```sh
+npm run dev     # dev server, hot reload
+npm run build   # writes dist/, prerenders what it can
+npm start       # serves the build
+npm run check   # type-check every .html and .js route
+```
+
+## Traps
+
+These are the mistakes to avoid. Each one is a real compile error or a real
+bug, not a style preference.
+
+**`${…}` inside a nested `<script>` or `<style>` is a compile error.** Text
+there reaches the page as written, so a value would land in code. `json(value)`
+is the one way through, and only as the entire text of the script. For a style,
+pass the value through a custom property, which is an attribute and is escaped.
+
+**A literal `${` cannot be written in a template.** There is no escape. Pass any
+text containing it in from the loader as data.
+
+**Directive values are expressions, not interpolations.** Write
+`each="note of notes"`, never `each="${notes}"`.
+
+**A `fragment` element cannot carry `if`, `else` or `each`.** A fragment is one
+element with one id, so it cannot be conditional or repeated. Put the condition
+on something inside it.
+
+**A light element cannot `if` or `each` over a value that changes.** It writes
+into the DOM it already rendered and never replaces a child. That is a compile
+error naming `shadow`. Add `export const shadow = true` or keep the list still.
+
+**`setHTMLUnsafe()`, never `innerHTML`.** `innerHTML` does not process nested
+declarative shadow roots, so a child element becomes a dead `<template>`.
+
+**An element file name needs a dash.** `note-card.html` is a valid custom
+element name. `card.html` is not, and the file is dropped.
+
+**`<transclude>` has no self-closing form.** `<transclude src="#a" />` is read
+as an open tag and the rest of the page becomes its fallback content.
+
+**Reading a cookie makes a page personal.** It is then not cached and not
+prerendered. Writing one does not do this; reading one does.
+
+**`ctx.response` is shared by reference.** Set `ctx.status` and headers on it
+directly. It is the object the whole chain holds.
+
+**A `<template>`'s children are not `childNodes`.** They live on `.content`.
+
+## Going further
+
+- [references/elements.md](references/elements.md) — custom elements, light and
+  shadow, props, state, form association
+- [references/fragments.md](references/fragments.md) — fragments, includes and
+  transclusion
+- [references/server.md](references/server.md) — cookies, middleware, security,
+  config, deployment
+
+Full documentation: https://transclude.dev/docs