makersclaw 0.5.2 → 0.7.0

package/templates/next/browser/app/layout.jsx

@@ -0,0 +1,94 @@
+import "./globals.css";
+import { Examples } from "../components/parts/fixture";
+import { surfaceNav } from "../surfaces";
+import AutoRefresh from "./auto-refresh";
+import ErrorRelay from "./error-relay";
+import EscapeRelay from "./escape-relay";
+import Shell from "./shell";
+
+// FIXED — the platform agent does not edit this file. Design lives in
+// app/shell.jsx and the surfaces; colour lives nowhere in the app.
+//
+// A browser app's layout (makersclaw.json "mode": "browser"). The app is
+// files: `next build` prerenders every page once, with `output: "export"`
+// (next.config.mjs), and the platform serves what it wrote. So nothing
+// here reads the request. There is no request: no headers(), no
+// cookies(), and no `dynamic` export, which an export refuses anyway.
+// Everything the server layout decides per request is decided here at
+// build, or in the browser.
+export const metadata = { title: process.env.CLAW_PRODUCT || "Artifact" };
+
+// The theme, decided in the browser before the body paints. It follows
+// the desk: the OS window opens the app with ?theme=light|dark, and the
+// product proxy keeps that query through its redirect and sets the
+// claw_theme cookie (Path=/, readable here) on the same answer, so every
+// later page reads the cookie. Dark when neither says: the desk is dark,
+// and so is the data-theme the build writes.
+//
+// Why there is no flash: an inline script in <head> runs while the HTML
+// is parsed, before anything paints, and _claw/theme.css after it still
+// blocks the first paint. suppressHydrationWarning on <html> covers the
+// one attribute React then finds changed. Anything that throws (a
+// browser with cookies off) leaves the build's dark.
+//
+// A plain string, not a function turned into one: what runs is exactly
+// what test/browser.test.mjs runs against a fake document.
+const THEME = `(function () {
+  try {
+    var d = document.documentElement;
+    var q = new URLSearchParams(location.search).get("theme");
+    var m = document.cookie.match(/(?:^|; )claw_theme=(light|dark)(?:;|$)/);
+    d.dataset.theme = q === "light" || q === "dark" ? q : m ? m[1] : "dark";
+  } catch (e) {}
+})();`;
+
+// <html> carries what the browser-side code reads: the base path for
+// lib/claw.js, the product name, the mode, the examples decision and
+// data-theme.
+//
+// The palette follows the WORKSPACE: <head> links `_claw/theme.css`, the
+// preset picked in System Settings → Appearance, served by the platform
+// with the page's own cookie as identity. app/globals.css holds the same
+// preset as defaults for a run with nothing serving it (a local `next
+// dev`, where the link 404s harmlessly). The href is prefixed by hand:
+// Next's basePath applies to next/link and assets, not to a literal
+// <link>.
+//
+// Examples (components/parts/fixture.jsx) are off inside a workspace, by
+// the server layout's own expression, read here at build: the platform
+// builds every browser app with its CLAW_ARTIFACT_ID, and its publish
+// refuses an export that says data-claw-examples="1". The store's own
+// loop builds without one, and shows its examples. The title and
+// data-claw-product are the name at build: a rename reaches them at the
+// next ship.
+export default function RootLayout({ children }) {
+  const basePath = process.env.CLAW_BASE_PATH || "";
+  const name = process.env.CLAW_PRODUCT || "Artifact";
+  const examples = process.env.CLAW_EXAMPLES === "1" || !process.env.CLAW_ARTIFACT_ID;
+  return (
+    <html
+      lang="en"
+      data-claw-base-path={basePath}
+      data-claw-product={name}
+      data-claw-mode="browser"
+      data-claw-examples={examples ? "1" : "0"}
+      data-theme="dark"
+      suppressHydrationWarning
+    >
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: THEME }} />
+        <link rel="stylesheet" href={`${basePath}/_claw/theme.css`} />
+      </head>
+      <body>
+        <AutoRefresh />
+        <ErrorRelay />
+        <EscapeRelay />
+        <Examples allowed={examples}>
+          <Shell name={name} surfaces={surfaceNav()}>
+            {children}
+          </Shell>
+        </Examples>
+      </body>
+    </html>
+  );
+}

package/templates/next/browser/app/page.jsx

@@ -0,0 +1,60 @@
+import { homeSurface } from "../surfaces";
+
+// FIXED — the platform agent does not edit this file.
+//
+// A browser app's "/" (makersclaw.json "mode": "browser"). As in a server
+// app it is never a page of its own: it sends the viewer to the home
+// surface, the entry flagged `home` in surfaces.js, else the first one.
+// Here the answer is decided once, at build.
+//
+// Not a redirect(). Under output "export" a redirect thrown while "/"
+// prerenders turns the exported index.html into Next's error shell
+// (<html id="__next_error__">, seen on 16.3.7): no layout, so no head
+// script and no palette link. The browser then reaches the home surface
+// by a client navigation, not a page load, so the head script never runs
+// and data-theme stays the build's dark, whatever the desk said. Every
+// member opens "/" first (the desk opens the app's home).
+//
+// So "/" is an ordinary page, rendered through the layout (its theme
+// script and _claw/theme.css are in the HTML), that forwards:
+//   1. a script, run as the HTML is parsed: location.replace to the home
+//      surface, keeping the query (?theme=, ?row=) and the hash. A full
+//      page load, so the surface's own head script runs.
+//   2. <meta http-equiv="refresh"> for a browser with no JavaScript. The
+//      browser acts on it only once the page has loaded, so the script
+//      goes first. React puts the <meta> in <head>.
+// The href is prefixed by hand: Next's basePath applies to next/link,
+// not to a literal URL.
+//
+// With no entry at all there is nowhere to send the viewer, so the page
+// says so instead of forwarding to /s/undefined. Plain Tailwind: this
+// page is seen for seconds, before the platform agent writes the
+// manifest.
+export default function Home() {
+  const home = homeSurface();
+  if (home) {
+    const to = `${process.env.CLAW_BASE_PATH || ""}/s/${encodeURIComponent(home.key)}`;
+    return (
+      <>
+        <meta httpEquiv="refresh" content={`0;url=${to}`} />
+        <script dangerouslySetInnerHTML={{ __html: forward(to) }} />
+        <p className="text-sm text-muted-foreground">
+          <a href={to}>Open {home.label}</a>
+        </p>
+      </>
+    );
+  }
+  return (
+    <div className="max-w-prose">
+      <p className="text-xs uppercase tracking-wide text-muted-foreground">Empty</p>
+      <h1 className="mt-1 text-lg font-semibold">No surfaces yet.</h1>
+      <p className="mt-2 text-sm text-muted-foreground">Makersclaw is listing them.</p>
+    </div>
+  );
+}
+
+/** The forwarding script. `to` is a JSON string, with `<` escaped so no
+ *  key can close the <script> it sits in. */
+function forward(to) {
+  return `location.replace(${JSON.stringify(to).replace(/</g, "\\u003c")} + location.search + location.hash);`;
+}

package/templates/next/browser/app/s/[key]/page.jsx

@@ -0,0 +1,95 @@
+import { Suspense } from "react";
+import { notFound } from "next/navigation";
+import surfaces from "../../../surfaces";
+
+// FIXED — the platform agent does not edit this file.
+//
+// A browser app's surface route (makersclaw.json "mode": "browser"). Every
+// surface is a file: the build prerenders /s/<key> once per manifest
+// entry, and a key that is not in the manifest is no page at all.
+export const dynamicParams = false;
+
+// The page a browser app builds while its manifest is empty. Next refuses
+// a dynamic route whose list is empty under export, so an app with no
+// surfaces yet builds this one page, which says so.
+const NONE = "_none";
+
+export function generateStaticParams() {
+  const keys = surfaces.map((s) => ({ key: s.key }));
+  return keys.length ? keys : [{ key: NONE }];
+}
+
+export async function generateMetadata({ params }) {
+  const { key } = await params;
+  const s = surfaces.find((x) => x.key === key);
+  const name = process.env.CLAW_PRODUCT || "Artifact";
+  return { title: s ? `${s.label} · ${name}` : name };
+}
+
+// One route for every surface. A manifest entry without a component is
+// planned (the platform agent has named it but not built it yet) and
+// says so; a built one renders its component with the entry's plain
+// data (never the component itself: a client surface cannot receive a
+// function).
+//
+// A page built once, as a file, has no request, so a surface gets no
+// searchParams: it reads ?row= and the rest with useSearchParams(). A
+// prerendered client component that reads useSearchParams outside a
+// Suspense boundary fails the build, so the surface renders inside one.
+// The export holds its fallback; the browser then renders the surface
+// with the page's query, and its hooks read the rows through the door.
+export default async function SurfacePage({ params }) {
+  const { key } = await params;
+  const s = surfaces.find((x) => x.key === key);
+  if (!s) {
+    if (key === NONE) return <NoSurfaces />;
+    notFound();
+  }
+  if (!s.component) return <Planned surface={s} />;
+  const Surface = s.component;
+  return (
+    <Suspense fallback={<SurfaceLoading />}>
+      <Surface surface={{ key: s.key, kind: s.kind ?? null, label: s.label, source: s.source ?? null }} />
+    </Suspense>
+  );
+}
+
+// What a surface shows until the browser renders it: one quiet line, the
+// template's own, so a slow first paint never reads as an empty table.
+function SurfaceLoading() {
+  return (
+    <p role="status" className="text-sm text-muted-foreground">
+      Loading…
+    </p>
+  );
+}
+
+function NoSurfaces() {
+  return (
+    <div className="max-w-prose">
+      <p className="text-xs uppercase tracking-wide text-muted-foreground">Empty</p>
+      <h1 className="mt-1 text-lg font-semibold">No surfaces yet.</h1>
+      <p className="mt-2 text-sm text-muted-foreground">Makersclaw is listing them.</p>
+    </div>
+  );
+}
+
+function Planned({ surface }) {
+  return (
+    <div className="max-w-prose">
+      <p className="text-xs uppercase tracking-wide text-muted-foreground">Planned</p>
+      <h1 className="mt-1 text-lg font-semibold">Makersclaw is building this</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        {surface.label}
+        {surface.kind ? ` will be a ${surface.kind}` : null}
+        {surface.source ? (
+          <>
+            {" "}
+            over <code className="font-mono text-xs">{surface.source}</code>
+          </>
+        ) : null}
+        . It appears here as soon as it is built.
+      </p>
+    </div>
+  );
+}

package/templates/next/browser/lib/actions.js

@@ -0,0 +1,16 @@
+// A browser app's writes (makersclaw.json "mode": "browser"). The same names
+// and shapes as a server app's lib/actions.js, so a surface keeps
+// `import { updateRow } from "../lib/actions"`; here they are plain
+// functions of the browser that go through the platform's data door
+// (lib/door.js), not Server Actions: a browser app has no server of its
+// own. Call them from "use client" files.
+//
+// Each resolves { ok } (insertRow { ok, id }, runAction { ok, result })
+// or { ok: false, error, code }, and never throws. They go one at a time,
+// in the order called. The door runs each in a transaction that knows
+// the member (claw.member_id, claw.member_email) and writes its activity
+// line, so nothing here logs. `surface` defaults to the <key> of /s/<key>
+// in the page's path. A write that answers ok calls dataChanged(), and
+// every hook on the page reads again.
+
+export { deleteRow, insertRow, moveRow, runAction, saveSetting, updateRow } from "./door";

package/templates/next/browser/lib/data.js

@@ -0,0 +1,43 @@
+import { surfaceOfPath } from "./platform";
+
+// A browser app's reads (makersclaw.json "mode": "browser"). The same names
+// and shapes as a server app's lib/data.js, so a surface keeps
+// `import { loadRows } from "../lib/data"`; here they run in the browser
+// and go through the platform's data door (lib/door.js), which knows who
+// is asking. So there is no pg, no next/headers and no server action
+// here: a browser app has no server of its own. Call them from "use
+// client" files. Each read resolves { …, error } and never throws.
+//
+// Also here: the hooks, which read on mount and again on dataChanged()
+// (every write that answers ok calls it), and whenLanded(), which waits
+// for those reads.
+
+export {
+  countBy,
+  countRows,
+  dataChanged,
+  loadActivity,
+  loadRow,
+  loadRows,
+  useActivity,
+  useCount,
+  useCountBy,
+  useRow,
+  useRows,
+  whenLanded,
+} from "./door";
+
+/** Sample rows get stable ids and a `_sample: true` marker (lib/sample.js,
+ *  pure), as in a server app. */
+export { markSample } from "./sample";
+
+/** The surface key of the page: the caller's (a string, or the page's
+ *  `surface` object), else the <key> of /s/<key> in the page's path.
+ *  null when there is none. A server app reads it from the request; a
+ *  browser app's page is a file and has none, so it reads the path. */
+export function currentSurface(explicit) {
+  if (typeof explicit === "string" && explicit) return explicit;
+  if (explicit && typeof explicit === "object" && typeof explicit.key === "string" && explicit.key) return explicit.key;
+  if (typeof location === "undefined") return null;
+  return surfaceOfPath(location.pathname) || null;
+}