makersclaw 0.6.0 → 0.7.0

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;
+}