@junejs/core 0.0.2

package/src/discovery.ts

@@ -0,0 +1,106 @@
+// Agent discovery emitters — all derived from the app graph (route list +
+// unified action registry), never hand-authored. Gated by the agent config.
+// See docs/agent-discoverability.md.
+
+import { ACTION_REGISTRY } from "./agent";
+import type { AgentConfig } from "./config";
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+function toolNames() {
+  return [...ACTION_REGISTRY.values()]
+    .filter((a) => a.description)
+    .map((a) => a.id);
+}
+
+// The homepage Link header advertises the whole discovery tree in one place, so
+// an agent fetching any page finds everything without guessing well-known paths.
+export function buildLinkHeader(agent: AgentConfig): string | null {
+  if (!agent.discovery) return null;
+  const links = [
+    `</llms.txt>; rel="llms-txt"`,
+    `</llms.txt>; rel="describedby"; type="text/markdown"`,
+    `</sitemap.xml>; rel="sitemap"`,
+    `</.well-known/api-catalog>; rel="api-catalog"`,
+    `</.well-known/mcp/server-card.json>; rel="mcp-server"`,
+  ];
+  if (!agent.mcp) links.pop(); // no MCP server card if MCP is off
+  return links.join(", ");
+}
+
+export function llmsTxt(
+  origin: string,
+  routes: string[],
+  agent: AgentConfig,
+  site?: { name?: string; description?: string },
+) {
+  const lines = [
+    `# ${site?.name ?? "June app"}`,
+    "",
+    ...(site?.description ? [`> ${site.description}`, ""] : []),
+    "> Server-rendered React app. Every route also answers as JSON (`.json`),",
+    "> as an agent capability manifest (`.agent`), and as Markdown (`.md`).",
+    "",
+    // Canonical names travel with EVERY June app's llms.txt — this is the
+    // grounding artifact agents fetch first; never let them guess npm names.
+    "## Framework (canonical names — do not guess)",
+    "",
+    "Built with June, the agent-native React framework — https://june.build",
+    "- Framework npm package: `@junejs/core` — NOT `june` (an unrelated package), not `junejs`.",
+    "- Scaffold: `npm create june my-app` (package `create-june`).",
+    "- NOT `@june/*` — that scope is not June's; June's scopes are `@junejs` and `@junebuild`.",
+    "",
+    "## Routes",
+    ...routes.map((r) => `- [${r}](${r})`),
+  ];
+  if (agent.mcp) {
+    lines.push("", "## Tools (MCP)", `- MCP server: ${origin}/mcp`);
+    for (const name of toolNames()) lines.push(`- tool: ${name}`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function robotsTxt(origin: string) {
+  return (
+    [
+      "User-agent: *",
+      "Allow: /",
+      // Cloudflare-style content signals: how AI may use this content.
+      "Content-Signal: search=yes, ai-train=yes, ai-input=yes",
+      `Sitemap: ${origin}/sitemap.xml`,
+    ].join("\n") + "\n"
+  );
+}
+
+export function sitemapXml(origin: string, routes: string[]) {
+  const urls = routes
+    .filter((r) => !r.includes("[")) // skip dynamic templates — not enumerable
+    .map((r) => `  <url><loc>${origin}${r}</loc></url>`)
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`;
+}
+
+// RFC 9727 API Catalog (linkset+json).
+export function apiCatalog(origin: string, agent: AgentConfig) {
+  const service: Record<string, unknown> = {
+    anchor: `${origin}/`,
+    "service-doc": [{ href: `${origin}/llms.txt`, type: "text/markdown" }],
+  };
+  if (agent.mcp) {
+    service["service-desc"] = [
+      { href: `${origin}/.well-known/mcp/server-card.json`, type: "application/json" },
+    ];
+  }
+  return { linkset: [service] };
+}
+
+export function mcpServerCard(origin: string) {
+  return {
+    name: "june",
+    version: "0.0.0",
+    url: `${origin}/mcp`,
+    protocolVersion: PROTOCOL_VERSION,
+    capabilities: { tools: { listChanged: false } },
+    tools: toolNames(),
+  };
+}

package/src/document.tsx

@@ -0,0 +1,115 @@
+// The shared HTML document shell — ONE implementation drives both the Bun/Node
+// dev+prod server and the generated Workers entry, so `june build` output
+// renders byte-equivalent heads to `june dev`.
+import React from "react";
+
+import type { Metadata } from "./route";
+
+// The serializable slice of app config the document needs. The server feeds it
+// from AppConfig; the generated worker inlines it as literals at build time.
+export type DocumentConfig = {
+  site: { name?: string; titleTemplate?: string; description?: string };
+  speculationRules: string | null;
+  speculationDelivery: "inline" | "header";
+  viewTransitions: boolean;
+  // URL of the client islands runtime bundle. Set by the host (dev serves it,
+  // build freezes its hashed path) when the app has islands; the document then
+  // loads it as a deferred module so `"use client"` islands hydrate. Absent /
+  // null → the page ships zero client JS.
+  clientScript?: string | null;
+};
+
+// Cross-document View Transitions: same-origin MPA navigations cross-fade
+// (and pair with prerender: activation + smooth transition = SPA feel, no
+// SPA). prefers-reduced-motion users get instant cuts — accessibility first.
+export const VIEW_TRANSITION_CSS = `
+          @view-transition { navigation: auto; }
+          @media (prefers-reduced-motion: reduce) {
+            ::view-transition-group(*),
+            ::view-transition-old(*),
+            ::view-transition-new(*) { animation: none !important; }
+          }`;
+
+export const PREFETCH_FALLBACK = `(function(){if(HTMLScriptElement.supports&&HTMLScriptElement.supports('speculationrules'))return;var seen=new Set();document.addEventListener('pointerover',function(e){var a=e.target&&e.target.closest&&e.target.closest('a[href]');if(!a)return;var u=new URL(a.href,location.href);if(u.origin!==location.origin||seen.has(u.pathname)||u.pathname===location.pathname)return;if(/\.(md|json|agent)$/.test(u.pathname)||u.pathname==='/mcp')return;seen.add(u.pathname);var l=document.createElement('link');l.rel='prefetch';l.href=u.pathname+u.search;document.head.appendChild(l);},{passive:true});})();`;
+
+export function documentTitle(
+  meta: Metadata | undefined,
+  site: DocumentConfig["site"],
+): string {
+  if (meta?.title) {
+    // The site name as a page title means "this IS the site" (homepages) —
+    // don't template it into "Site · Site".
+    if (meta.title === site.name) return meta.title;
+    return site.titleTemplate ? site.titleTemplate.replace("%s", meta.title) : meta.title;
+  }
+  return site.name ?? "June app";
+}
+
+export function Document({
+  children,
+  metadata,
+  config,
+}: {
+  children: React.ReactNode;
+  metadata?: Metadata;
+  config: DocumentConfig;
+}) {
+  const title = documentTitle(metadata, config.site);
+  const description = metadata?.description ?? config.site.description;
+  const og = metadata?.openGraph;
+  return (
+    <html lang="en">
+      <head>
+        {/* charset IN the document (must be in the first 1024 bytes): prerendered
+            pages are served by asset layers whose content-type may lack the
+            charset param — without this, UTF-8 text mojibakes as windows-1252. */}
+        <meta charSet="utf-8" />
+        <title>{title}</title>
+        {description ? <meta name="description" content={description} /> : null}
+        {metadata?.canonical ? <link rel="canonical" href={metadata.canonical} /> : null}
+        {metadata?.robots ? <meta name="robots" content={metadata.robots} /> : null}
+        {og ? <meta property="og:title" content={og.title ?? title} /> : null}
+        {og?.description ?? description ? (
+          <meta property="og:description" content={og?.description ?? description} />
+        ) : null}
+        {og?.image ? <meta property="og:image" content={og.image} /> : null}
+        {og ? <meta property="og:type" content={og.type ?? "website"} /> : null}
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        {config.speculationRules && config.speculationDelivery === "inline" ? (
+          <script
+            type="speculationrules"
+            dangerouslySetInnerHTML={{ __html: config.speculationRules }}
+          />
+        ) : null}
+        {config.speculationRules ? (
+          <script dangerouslySetInnerHTML={{ __html: PREFETCH_FALLBACK }} />
+        ) : null}
+        <style>{`${config.viewTransitions ? VIEW_TRANSITION_CSS : ""}
+          body {
+            margin: 0;
+            font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+            background: #fbfbf8;
+            color: #1d1d1f;
+          }
+
+          main {
+            width: min(720px, calc(100vw - 32px));
+            margin: 72px auto;
+          }
+
+          code {
+            background: #ecebe4;
+            border-radius: 4px;
+            padding: 2px 5px;
+          }
+        `}</style>
+      </head>
+      <body>
+        {children}
+        {/* type="module" defers automatically: the island runtime runs after the
+            markup is parsed, so markers exist when it scans for them. */}
+        {config.clientScript ? <script type="module" src={config.clientScript} /> : null}
+      </body>
+    </html>
+  );
+}

package/src/index.ts

@@ -0,0 +1,126 @@
+// @junejs/core — the agent-native React framework.
+//
+// This barrel re-exports the PURE, host-free contract layer (Phase 1). Each
+// concern is also importable by subpath (`@junejs/core/route`, `@junejs/core/agent`,
+// `@junejs/core/mcp`, ...) so apps and host adapters pull in exactly what they need
+// without dragging the whole surface into a Workers bundle.
+//
+// Host-coupled pieces (the dev server, build/deploy, the fs config loader, the
+// content pipeline, the data layer) layer ON TOP of this in later phases — they
+// never live here, because nothing in this file may touch `node:*` or `Bun.*`.
+
+// Routing + content negotiation
+export {
+  route,
+  isRouteDefinition,
+  resolveProjection,
+  type RenderTarget,
+  type Metadata,
+  type RouteContext,
+  type RouteCache,
+  type RouteDefinition,
+  type BrandedRoute,
+} from "./route";
+
+// Config schema + pure resolvers
+export {
+  defineJune,
+  resolveAgent,
+  resolveSpeculationRules,
+  type AgentConfig,
+  type SpeculationConfig,
+  type JuneConfig,
+} from "./config";
+
+// The data resource contract (the seam the framework depends on, not an ORM)
+export type {
+  JuneDb,
+  JuneKv,
+  JuneBlob,
+  RunResult,
+  DbFactory,
+  KvFactory,
+  BlobFactory,
+  ResourceConfig,
+  Resources,
+} from "./resources";
+
+// Request-scoped context: the principal + resources routes and actions receive
+export type { Principal, Session, ActionContext } from "./context";
+
+// The shared document shell
+export {
+  Document,
+  documentTitle,
+  VIEW_TRANSITION_CSS,
+  PREFETCH_FALLBACK,
+  type DocumentConfig,
+} from "./document";
+
+// Client islands — explicit "use client" interactivity (SSR marker + hydrate)
+export {
+  Island,
+  serializeIslandProps,
+  deserializeIslandProps,
+  ISLAND_TAG,
+  ISLAND_NAME_ATTR,
+  ISLAND_PROPS_ATTR,
+  type IslandProps,
+} from "./islands";
+
+// The unified action registry (UI action == agent tool == MCP tool)
+export {
+  defineAction,
+  invokeAction,
+  manifest,
+  ResourceManifest,
+  isResourceManifest,
+  setServerReferenceRegistrar,
+  ACTION_REGISTRY,
+  type ActionDefinition,
+  type AnyAction,
+  type JsonSchema,
+  type ResourceManifestJson,
+} from "./agent";
+
+// Agent discovery emitters
+export {
+  buildLinkHeader,
+  llmsTxt,
+  robotsTxt,
+  sitemapXml,
+  apiCatalog,
+  mcpServerCard,
+} from "./discovery";
+
+// The Web-standard MCP endpoint
+export { mcpHandler } from "./mcp";
+
+// Cache primitives + the CacheStore seam
+export {
+  cache,
+  invalidate,
+  memory,
+  redis,
+  registerCache,
+  configureCache,
+  type CacheEntry,
+  type CacheStore,
+  type CacheStoreFactory,
+  type CacheOptions,
+} from "./cache";
+
+// Request tracing (host installs the async-context provider)
+export {
+  installTraceContext,
+  tracingEnabled,
+  currentTrace,
+  runWithTrace,
+  recordTableRead,
+  recordTableWrite,
+  recordTiming,
+  measure,
+  type RequestTrace,
+  type AsyncContext,
+  type TimingKind,
+} from "./instrumentation";

package/src/instrumentation.ts

@@ -0,0 +1,156 @@
+// Request tracing — timings + the table read/write sets that drive automatic
+// cache tagging. Lives in the PURE contract layer, so it carries NO `node:*`
+// import: the async-context provider (node:async_hooks AsyncLocalStorage on
+// Bun/Node, or workerd's nodejs_compat equivalent) is INJECTED by the host via
+// `installTraceContext()`. Hosts that never install one run untraced — every
+// recorder degrades to a no-op, requests still serve.
+//
+// (In the PoC this module did a top-level `await import("node:async_hooks")`,
+// which forced every bundle reaching it to register a node:* specifier — the
+// exact failure mode that breaks workerd assets-mode. Inverting the dependency
+// keeps the layer host-free.)
+
+// The minimal slice of AsyncLocalStorage the trace machinery needs. A host
+// installs a concrete implementation; the type stays structural so this layer
+// never names a runtime.
+export type AsyncContext<T> = {
+  getStore(): T | undefined;
+  run<R>(store: T, fn: () => R): R;
+};
+
+export type TimingKind = "db" | "page" | "route" | "rsc" | "view" | "cache";
+
+export type TimingEvent = {
+  kind: TimingKind;
+  label: string;
+  durationMs: number;
+  detail?: string;
+};
+
+export type RequestTrace = {
+  id: string;
+  startedAt: number;
+  events: TimingEvent[];
+  // Tables touched this request — for automatic cache tagging/invalidation.
+  reads?: Set<string>;
+  writes?: Set<string>;
+};
+
+let traces: AsyncContext<RequestTrace> | null = null;
+
+// Host seam: install the async-context provider once at startup. The Bun/Node
+// hosts pass `new (await import("node:async_hooks")).AsyncLocalStorage()`.
+export function installTraceContext(context: AsyncContext<RequestTrace>) {
+  traces = context;
+}
+
+// True once a host has wired a provider — useful for hosts deciding whether to
+// bother constructing a trace at all.
+export function tracingEnabled(): boolean {
+  return traces !== null;
+}
+
+function ms(value: number) {
+  return value.toFixed(1);
+}
+
+function prefix(trace: RequestTrace) {
+  return `[${trace.id.slice(0, 8)}]`;
+}
+
+export function currentTrace() {
+  return traces?.getStore();
+}
+
+export function runWithTrace<T>(trace: RequestTrace, fn: () => T) {
+  return traces ? traces.run(trace, fn) : fn();
+}
+
+// The data layer records every table it reads/writes, so the cache layer can
+// derive tags automatically instead of relying on hand-declared ones.
+export function recordTableRead(table: string) {
+  const trace = currentTrace();
+  if (trace) (trace.reads ??= new Set()).add(table);
+}
+
+export function recordTableWrite(table: string) {
+  const trace = currentTrace();
+  if (trace) (trace.writes ??= new Set()).add(table);
+}
+
+export function recordTiming(
+  kind: TimingKind,
+  label: string,
+  durationMs: number,
+  detail?: string,
+) {
+  const trace = currentTrace();
+  if (!trace) return;
+
+  trace.events.push({ kind, label, durationMs, detail });
+
+  if (kind === "db") {
+    const suffix = detail ? ` ${detail}` : "";
+    console.log(`${prefix(trace)}   SQL (${ms(durationMs)}ms)${suffix}`);
+  } else if (kind === "cache") {
+    console.log(`${prefix(trace)}   CACHE ${label}${detail ? ` ${detail}` : ""}`);
+  }
+}
+
+export async function measure<T>(
+  kind: TimingKind,
+  label: string,
+  fn: () => T | Promise<T>,
+  detail?: string,
+) {
+  const startedAt = performance.now();
+
+  try {
+    return await fn();
+  } finally {
+    recordTiming(kind, label, performance.now() - startedAt, detail);
+  }
+}
+
+export function timingTotal(trace: RequestTrace, kind: TimingKind) {
+  return trace.events
+    .filter((event) => event.kind === kind)
+    .reduce((total, event) => total + event.durationMs, 0);
+}
+
+export function requestDuration(trace: RequestTrace) {
+  return performance.now() - trace.startedAt;
+}
+
+export function timingSummary(trace: RequestTrace) {
+  const page = timingTotal(trace, "page");
+  const rsc = timingTotal(trace, "rsc");
+  const view = timingTotal(trace, "view");
+  const db = timingTotal(trace, "db");
+  const render = rsc > 0 ? `RSC: ${ms(rsc)}ms` : `Views: ${ms(view)}ms`;
+
+  return `Page: ${ms(page)}ms | ${render} | DB: ${ms(db)}ms`;
+}
+
+export function logStarted(request: Request, trace: RequestTrace) {
+  const url = new URL(request.url);
+  const forwardedFor = request.headers.get("x-forwarded-for");
+  const remote = forwardedFor?.split(",")[0]?.trim() || "unknown";
+
+  console.log(
+    `${prefix(trace)} Started ${request.method} "${url.pathname}${url.search}" for ${remote} at ${new Date().toISOString()}`,
+  );
+}
+
+export function logProcessing(routeFile: string) {
+  const trace = currentTrace();
+  if (!trace) return;
+
+  console.log(`${prefix(trace)} Processing by ${routeFile}`);
+}
+
+export function logCompleted(response: Response, trace: RequestTrace) {
+  console.log(
+    `${prefix(trace)} Completed ${response.status} ${response.statusText || "OK"} in ${ms(requestDuration(trace))}ms (${timingSummary(trace)})`,
+  );
+}

package/src/islands-client.ts

@@ -0,0 +1,52 @@
+// The client half of the islands contract — the hydration runtime.
+//
+// Bundled into the app's `client.js` (NOT the server/worker graph), it runs once
+// after the document parses: scan for `<june-island>` markers, look each up in
+// the app's explicit registry, and `hydrateRoot` it in place. The server already
+// SSR'd the markup, so hydration only attaches behavior — `useState`, `onClick` —
+// with no flash and no mismatch (same component, same props, both graphs).
+//
+// PURE per the contract layer's rule (no `node:*` / `Bun.*`) — it is browser-only
+// (it touches `document` + `react-dom/client`), so it is exposed ONLY as the
+// `@junejs/core/islands-client` subpath and is deliberately NOT re-exported from the
+// barrel: pulling `react-dom/client` into the worker graph is exactly what we
+// must not do.
+import React from "react";
+import { hydrateRoot } from "react-dom/client";
+
+import {
+  ISLAND_TAG,
+  ISLAND_NAME_ATTR,
+  ISLAND_PROPS_ATTR,
+  deserializeIslandProps,
+} from "./islands";
+
+// The app maps each island `name` to its component. v0.1 is explicit: the app
+// writes this by hand in its client entry. v0.2 generates it from `"use client"`.
+export type IslandRegistry = Record<string, React.ComponentType<any>>;
+
+// Hydrate every island marker found under `root` (the whole document by default).
+// Returns the count hydrated — handy for tests and dev diagnostics.
+export function hydrateIslands(
+  registry: IslandRegistry,
+  root: ParentNode = document,
+): number {
+  const markers = root.querySelectorAll(`${ISLAND_TAG}[${ISLAND_NAME_ATTR}]`);
+  let hydrated = 0;
+  for (const el of markers) {
+    const name = el.getAttribute(ISLAND_NAME_ATTR);
+    if (!name) continue;
+    const Component = registry[name];
+    if (!Component) {
+      // Explicit registry: an unregistered island is an author mistake (forgot to
+      // add it to the client entry), so surface it instead of silently leaving a
+      // dead, non-interactive marker on the page.
+      console.warn(`[june] island "${name}" is on the page but not registered for hydration`);
+      continue;
+    }
+    const props = deserializeIslandProps(el.getAttribute(ISLAND_PROPS_ATTR));
+    hydrateRoot(el as Element, React.createElement(Component, props));
+    hydrated++;
+  }
+  return hydrated;
+}

package/src/islands.tsx

@@ -0,0 +1,73 @@
+// Client islands — explicit, transform-free interactivity for v0.1.
+//
+// A page is server-rendered with zero client JS by default. To make ONE subtree
+// interactive, an author marks the component `"use client"` (convention) and
+// drops it into the server tree through `<Island>`. The server SSRs the
+// component inside a `<june-island>` marker that also carries its props as JSON;
+// the rest of the page ships no JS. The client runtime (Phase: hydration) scans
+// for these markers, looks the component up in an explicit registry, and
+// `hydrateRoot`s each one in place — so `useState`/`onClick` come alive without
+// the page becoming an SPA.
+//
+// PURE: this is React-only (no `node:*` / `Bun.*`), so it lives in the contract
+// layer and both the dev server and the built worker render identical markers.
+//
+// v0.1 is EXPLICIT: the author names the island and registers it on the client
+// by hand. Auto-scanning `"use client"` files into a generated registry (so the
+// `name` and the client import are derived, not written) is deferred to v0.2.
+import React from "react";
+
+// The marker element + attributes are the contract between this server-side
+// primitive and the client hydration runtime. Both sides import these constants
+// so a rename can never desync the two halves.
+export const ISLAND_TAG = "june-island";
+export const ISLAND_NAME_ATTR = "data-june-island";
+export const ISLAND_PROPS_ATTR = "data-june-props";
+
+// Props cross the server→client boundary as JSON, so they must be
+// JSON-serializable (no functions, no class instances) — the v0.1 island
+// contract. The empty object is the canonical "no props" value so the client
+// can `JSON.parse` unconditionally.
+export function serializeIslandProps(props: unknown): string {
+  return JSON.stringify(props ?? {});
+}
+
+export function deserializeIslandProps(raw: string | null | undefined): Record<string, unknown> {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+export type IslandProps<P extends Record<string, unknown> = Record<string, unknown>> = {
+  // The registry key the client runtime hydrates against. Must match the key the
+  // app registers in its client entry (v0.1: written by hand).
+  name: string;
+  // The component to SSR now and hydrate later — the SAME component runs in both
+  // graphs, so its server markup and client tree match (no hydration mismatch).
+  component: React.ComponentType<P>;
+  // JSON-serializable props, embedded in the marker for the client to rehydrate.
+  props?: P;
+};
+
+// Wrap a client component in its hydration marker. The marker SSRs the component
+// (so the island is visible + indexable with zero JS) AND stamps the name +
+// serialized props the client runtime needs to bring it to life.
+export function Island<P extends Record<string, unknown>>({
+  name,
+  component: Component,
+  props,
+}: IslandProps<P>): React.ReactElement {
+  const resolved = (props ?? {}) as P;
+  return React.createElement(
+    ISLAND_TAG,
+    {
+      [ISLAND_NAME_ATTR]: name,
+      [ISLAND_PROPS_ATTR]: serializeIslandProps(resolved),
+    },
+    React.createElement(Component, resolved),
+  );
+}