@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/legacy/caret.ts

@@ -0,0 +1,246 @@
+import { FIELD_ATTR, RICH_ATTR } from './shape'
+
+/**
+ * Which marked elements take a caret, and where the caret goes.
+ *
+ * Split out of `bridge.tsx` for two reasons. It is the only part of the editing behaviour
+ * that is pure DOM — no React, no message protocol, no closure over the bridge's state — so
+ * it can be loaded and driven on its own, which is what `verify:caret` does: it runs these
+ * exact functions in a real browser against a real layout, rather than a transcription of
+ * them that could drift. And `bridge.tsx` was over a thousand lines.
+ */
+
+/**
+ * What an annotated element must not contain if it is to be typed into.
+ *
+ * A marked element holding an image or a video is a media field or a card, not words: its
+ * value is an upload id, and the caret has no business there. A nested control or link is
+ * excluded for a different reason — its own text is a separate field, or markup a plain
+ * string cannot round-trip, so editing the parent as one blob would flatten it.
+ *
+ * **`svg` is deliberately absent.** Every button on these sites is `<a>Contact Us<svg/></a>`
+ * — the label and its chevron — and excluding icons would have made the most obviously
+ * editable thing on the page the one thing you could not edit. `innerText` ignores an svg's
+ * contents, so the value is the words alone; and if a client deletes the icon while typing,
+ * the re-render on blur puts it straight back, because the icon was never theirs to store.
+ *
+ * The check is on *descendants* — an `<a>` that is itself the marked element is fine.
+ */
+export const NON_TEXT = 'img, picture, video, canvas, iframe, input, textarea, select, button, a'
+
+/**
+ * The tags that are a picture rather than words — a deliberate *subset* of `NON_TEXT`.
+ *
+ * Two lists rather than one, and the difference is `a` and `button`. `NON_TEXT` answers "may
+ * this element *contain* something untypable", and a marked button label is both a control and
+ * a text leaf: with navigation off it takes a caret, which is how a client edits a button's
+ * words at all. Excluding every non-text tag from editability would therefore make every
+ * caption on every button uneditable in place — a far worse bug than the one this fixes.
+ *
+ * This list answers a different question: "*is* this element a picture". `NON_TEXT` could never
+ * answer it, because it is only ever asked about descendants — `querySelector`, `:has()` — and
+ * an `<img>` contains no `img`. So a marked image satisfied every editable-leaf test and
+ * offered an I-beam over a photograph.
+ */
+export const MEDIA = 'img, picture, video, canvas, iframe'
+
+/**
+ * A marked element that is itself a picture.
+ *
+ * Keyed on the element's own tag rather than on what it contains, because the two spellings a
+ * site uses want different treatment: a marker *on* the image needs its affordance drawn inside
+ * itself, while a marker on a wrapper is normally the clipping frame and its outline is already
+ * visible outside it.
+ */
+export const MEDIA_SELECTOR = `[${FIELD_ATTR}]:is(${MEDIA})`
+
+/**
+ * Whether this annotated element is a leaf holding text, and so directly editable.
+ *
+ * Leaf means it contains no other annotated element. A container — a card marked as a
+ * whole, a section wrapping four marked children — would otherwise become one editable
+ * blob whose text belongs to several fields at once, and the first keystroke would write
+ * all of them into one.
+ *
+ * **A rich field is accepted here early**, ahead of the nested-marker and `NON_TEXT`
+ * clauses below, and that ordering is the point: a real document contains `<a>` and `<ul>`,
+ * and both of those clauses exist to stop an *ordinary* field being edited as one blob —
+ * applied to a rich field they would reject it for exactly the structure it is allowed to
+ * hold. The requirement was never "a rich field must not be edited in place"; a client
+ * choosing to type into their own heading is the same client choosing to type into their
+ * own paragraph. The requirement is "a rich field must never be read back as plain words",
+ * and that guarantee is the bridge's job — see `flushEdit`'s branch on `RICH_ATTR` — not
+ * this function's.
+ *
+ * The `MEDIA` clause still runs unconditionally, ahead of the rich check: a marker on an
+ * image is a picture whatever else it carries, and the caret has no business there.
+ */
+export const isEditableLeaf = (element: HTMLElement): boolean => {
+  if (element.matches(MEDIA)) return false
+  if (element.hasAttribute(RICH_ATTR)) return Boolean(element.textContent?.trim())
+
+  return (
+    !element.querySelector(`[${FIELD_ATTR}]`) &&
+    !element.querySelector(NON_TEXT) &&
+    Boolean(element.textContent?.trim())
+  )
+}
+
+/**
+ * The CSS spelling of `isEditableLeaf`, for the hover affordance.
+ *
+ * Built from the same constants so the I-beam and the behaviour cannot disagree about what
+ * is typable. `:is([${RICH_ATTR}], …)` is the OR that mirrors the early return above: a
+ * rich field takes the I-beam without also having to clear the nested-marker and `NON_TEXT`
+ * clauses, which exist to protect an ordinary field and would otherwise disqualify a real
+ * document for the very links and lists it is allowed to contain.
+ *
+ * `:not(:is(${MEDIA}))` still runs unconditionally, outside that `:is()` — a marked image is
+ * a picture, rich or not, and the caret has no business there either.
+ *
+ * The one clause CSS still cannot express is "and it has some text in it" — an empty marked
+ * element therefore offers an I-beam and does nothing when clicked, which is the least
+ * interesting way for the two to fall out of step and beats making every site component
+ * carry a class.
+ */
+export const EDITABLE_LEAF_SELECTOR = `[${FIELD_ATTR}]:not(:is(${MEDIA})):is([${RICH_ATTR}], :not(:has([${FIELD_ATTR}])):not(:has(${NON_TEXT})))`
+
+/**
+ * A collapsed range at a viewport point, across both spellings of the same API.
+ *
+ * `caretPositionFromPoint` is the standard one and what Firefox has always had;
+ * `caretRangeFromPoint` is WebKit's older name for it, still what Safari ships. Chromium
+ * answers to both. Neither is guaranteed, hence the null.
+ */
+export const caretFromPoint = (x: number, y: number): null | Range => {
+  const doc = document as Document & {
+    caretPositionFromPoint?: (x: number, y: number) => null | { offset: number; offsetNode: Node }
+    caretRangeFromPoint?: (x: number, y: number) => null | Range
+  }
+
+  if (typeof doc.caretPositionFromPoint === 'function') {
+    const position = doc.caretPositionFromPoint(x, y)
+    if (!position) return null
+    const range = document.createRange()
+    range.setStart(position.offsetNode, position.offset)
+    range.collapse(true)
+    return range
+  }
+
+  if (typeof doc.caretRangeFromPoint === 'function') {
+    const range = doc.caretRangeFromPoint(x, y)
+    range?.collapse(true)
+    return range
+  }
+
+  return null
+}
+
+/**
+ * Where the caret should go for a click at this point — resolved, not yet applied.
+ *
+ * ## Call this *before* making the element editable
+ *
+ * The split into resolve-then-apply is the whole point of this pair, and it is not
+ * stylistic. Both inputs it reads are changed by `contenteditable`:
+ *
+ *  - The point lookup. Measured on Chromium against `<a>Contact Us<svg/></a>` laid out as
+ *    `inline-flex`: with the element inert, x-positions across the label resolve to text
+ *    offsets 9, 12, 13 as you would expect. Set `contenteditable` first and every one of
+ *    them comes back as offset 0 instead. The caret then lands at the front of the label
+ *    however carefully the client aimed — which was the original bug wearing a new hat.
+ *  - Any selection the browser has already made. `focus()` on a freshly editable element
+ *    can collapse it, and a double-click's word selection is exactly that.
+ *
+ * So: resolve here, `beginEditing`, then `applyCaret`. Both call sites in `bridge.tsx` do
+ * that in that order, and it is why they hold a `Range` across the two.
+ *
+ * An existing run of selected text wins over the point. A press-and-drag across three words
+ * *is* a selection and the click ending it must not collapse it to a caret; the same clause
+ * is what keeps a double-click meaning "replace this word".
+ */
+export const caretTargetIn = (element: HTMLElement, x: number, y: number): Range => {
+  const selection = window.getSelection()
+
+  if (selection && !selection.isCollapsed && selection.rangeCount > 0) {
+    const existing = selection.getRangeAt(0)
+    // Cloned: the live range would be mutated by the focus that happens in between.
+    if (element.contains(existing.commonAncestorContainer)) return existing.cloneRange()
+  }
+
+  const fromPoint = caretFromPoint(x, y)
+  return fromPoint && landsInText(element, fromPoint) ? fromPoint : endOf(element)
+}
+
+/** Apply a range resolved by `caretTargetIn`, after the element has been made editable. */
+export const applyCaret = (range: Range): void => {
+  const selection = window.getSelection()
+  if (!selection) return
+  selection.removeAllRanges()
+  selection.addRange(range)
+}
+
+/**
+ * Whether a point lookup found somewhere a caret can actually sit.
+ *
+ * Three things have to hold, and the third is why this is a function rather than a
+ * `contains` call. Every button on these sites is `<a>Contact Us<svg/></a>`, and clicking
+ * the chevron resolves to a `path` node — which *is* inside the marked element, so a
+ * containment check alone accepts it and the caret is placed inside the icon. Typing then
+ * goes nowhere the client can see. The svg check is belt-and-braces on top of the text-node
+ * one: an `<svg><text>` would satisfy both otherwise.
+ *
+ * Anything rejected falls back to the end of the words, which for a button label clicked on
+ * its icon is where you wanted the caret anyway.
+ */
+const landsInText = (element: HTMLElement, range: Range): boolean => {
+  const container = range.startContainer
+  if (container.nodeType !== Node.TEXT_NODE) return false
+  if (!element.contains(container)) return false
+  return !container.parentElement?.closest('svg')
+}
+
+/**
+ * A collapsed range after the element's last visible character.
+ *
+ * **Not `selectNodeContents` + `collapse(false)`**, which is the obvious spelling and is
+ * wrong here. That produces a position anchored to the *element* just past its last child,
+ * and for `<a>Contact Us<svg/> </a>` the last child is collapsible whitespace after an icon
+ * — no visible caret position at all. Chromium normalises it, and measurably normalises it
+ * to the *front* of the element: typing after clicking the chevron inserted at the start of
+ * the label, which is the exact failure the fallback exists to avoid.
+ *
+ * So it anchors to the last text node that actually holds words, at the end of those words
+ * rather than the end of the node — trailing whitespace inside a text node is no better a
+ * caret position than trailing whitespace between them.
+ */
+const endOf = (element: HTMLElement): Range => {
+  const range = document.createRange()
+  const last = lastWordsIn(element)
+
+  if (!last) {
+    // No text at all. `isEditableLeaf` rules this out for the click path; a direct caller
+    // gets the old behaviour, which is the only thing available.
+    range.selectNodeContents(element)
+    range.collapse(false)
+    return range
+  }
+
+  range.setStart(last, (last.textContent ?? '').replace(/\s+$/, '').length)
+  range.collapse(true)
+  return range
+}
+
+/** The last text node holding something other than whitespace, icons excluded. */
+const lastWordsIn = (element: HTMLElement): null | Text => {
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, {
+    acceptNode: (node) =>
+      node.textContent?.trim() && !node.parentElement?.closest('svg')
+        ? NodeFilter.FILTER_ACCEPT
+        : NodeFilter.FILTER_REJECT,
+  })
+
+  let last: null | Text = null
+  while (walker.nextNode()) last = walker.currentNode as Text
+  return last
+}

package/src/legacy/cli.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from 'node:fs/promises'
+
+/**
+ * `npx --yes @unitninety/u90@1.0.0 pair <code>` — the one command an operator hands over. The u90 tool
+ * runs this file for `u90 pair`. The command is scoped and pinned because an unscoped name, run in a
+ * repository with no local bin, fetches whatever package npm holds under that name.
+ *
+ * Claims this site's credentials, writes them to `.env.local`, then tells the platform
+ * where the site lives. Two calls rather than one, because the platform *fetches* the
+ * manifest instead of accepting one — and it can only authenticate that fetch once this
+ * site holds the secret.
+ *
+ * Nothing is printed that shouldn't be: the API key and revalidate secret go to the file
+ * and never to stdout, because a terminal scrollback is exactly the kind of place
+ * secrets survive in.
+ *
+ * **Plain `.mjs`, and dependency-free — `node:` builtins only.** Both on purpose. This
+ * is the first thing that runs in a fresh repo, so it cannot need an install step or a
+ * build step to work. `.ts` would have been fine on Node 22.18+, where type stripping is
+ * unflagged, and would have failed with `Unknown file extension ".ts"` on the Node 20
+ * that Next still supports — a bootstrap tool that only starts on new runtimes is a
+ * bootstrap tool with a bootstrap problem. The one type it used (`PairedCredentials`,
+ * in `contract.ts`) was erased at runtime anyway.
+ */
+
+const ENV_FILE = '.env.local'
+
+/** @returns {never} */
+const fail = (message) => {
+  console.error(`\n  ${message}\n`)
+  process.exit(1)
+}
+
+/** Which platform to pair against. The code doesn't carry it. */
+const platformFromArgs = (args) => {
+  const flag = args.findIndex((arg) => arg === '--platform')
+  if (flag !== -1 && args[flag + 1]) return args[flag + 1].replace(/\/$/, '')
+  if (process.env.PLATFORM_URL) return process.env.PLATFORM_URL.replace(/\/$/, '')
+  return 'https://run.unitninety.com'
+}
+
+/** This site's public origin, which the platform has to be able to reach. */
+const siteUrlFromArgs = (args) => {
+  const flag = args.findIndex((arg) => arg === '--site')
+  if (flag !== -1 && args[flag + 1]) return args[flag + 1].replace(/\/$/, '')
+  if (process.env.SITE_URL) return process.env.SITE_URL.replace(/\/$/, '')
+  return fail(
+    "This site's public URL is needed, so the platform can fetch its content schema.\n" +
+      '  Pass --site https://example.com (or set SITE_URL).',
+  )
+}
+
+/** The four keys pairing owns. Everything else in the file is left untouched. */
+const PAIRED_KEYS = ['PLATFORM_URL', 'PAYLOAD_API_KEY', 'REVALIDATE_SECRET', 'SITE_URL']
+
+/**
+ * Write the paired values, replacing any this command set before.
+ *
+ * **Superseded, not deleted.** This used to append and leave the old block in place,
+ * reasoning that silently editing someone's env file is how a working deployment breaks at
+ * 5pm — dotenv takes the last value, so appending was both effective and reversible.
+ *
+ * True, and it cost an hour anyway. Pair a site twice and every key appears twice with
+ * different values, the dead block reads exactly like the live one, and the first thing
+ * anyone debugging a 401 does is read the file from the top. That is a worse trap than the
+ * one the appending avoided, because it is silent and it looks fine.
+ *
+ * So old values are commented out where they stand, with the date that retired them, and
+ * the new block goes on the end. One live value per key, nothing destroyed, and going back
+ * is uncommenting a line.
+ */
+const writeEnv = async (credentials, siteUrl, platform) => {
+  const existing = await readFile(ENV_FILE, 'utf8').catch(() => '')
+  const stamp = new Date().toISOString()
+
+  const superseded = []
+
+  const retired = existing
+    .split('\n')
+    .map((line) => {
+      const key = PAIRED_KEYS.find((candidate) => line.startsWith(`${candidate}=`))
+      if (!key) return line
+      superseded.push(key)
+      // Kept in full, including the value: this is a gitignored local file, and a
+      // recoverable old key is the whole point of not simply dropping the line.
+      return `# superseded by \`u90 pair\` on ${stamp}: ${line}`
+    })
+    .join('\n')
+
+  if (superseded.length > 0) {
+    console.log(
+      `\n  Note: ${ENV_FILE} already set ${[...new Set(superseded)].join(', ')}.\n` +
+        '  Those lines are now commented out with today’s date, and the new values are below them.',
+    )
+  }
+
+  await writeFile(
+    ENV_FILE,
+    [
+      retired.replace(/\n+$/, ''),
+      '',
+      `# Added by \`u90 pair\` on ${stamp}`,
+      `PLATFORM_URL=${credentials.platformUrl || platform}`,
+      `PAYLOAD_API_KEY=${credentials.apiKey}`,
+      `REVALIDATE_SECRET=${credentials.revalidateSecret}`,
+      `SITE_URL=${siteUrl}`,
+      '',
+    ].join('\n'),
+    'utf8',
+  )
+}
+
+const run = async () => {
+  const args = process.argv.slice(2)
+
+  if (args[0] !== 'pair' || !args[1]) {
+    fail('Usage: npx --yes @unitninety/u90@1.0.0 pair <code> --site https://example.com [--platform https://cms…]')
+  }
+
+  const code = args[1]
+  const platform = platformFromArgs(args)
+  const siteUrl = siteUrlFromArgs(args)
+
+  console.log(`\n  Pairing with ${platform}…`)
+
+  const paired = await fetch(`${platform}/api/u90/pair`, {
+    body: JSON.stringify({ code }),
+    headers: { 'Content-Type': 'application/json' },
+    method: 'POST',
+  }).catch(() => fail(`Could not reach ${platform}.`))
+
+  if (!paired.ok) {
+    const body = await paired.json().catch(() => ({}))
+    fail(
+      body.error ??
+        `The platform refused the pairing code (HTTP ${paired.status}). Codes are single use and expire after 15 minutes — ask for a new one.`,
+    )
+  }
+
+  const credentials = await paired.json()
+
+  await writeEnv(credentials, siteUrl, platform)
+  console.log(`  Credentials written to ${ENV_FILE}.`)
+
+  /*
+   * Registration happens *after* the env is written, on purpose. The platform fetches
+   * this site's manifest during registration, and that fetch is authenticated with the
+   * secret we have only just received — so a site that hasn't stored it yet cannot be
+   * verified.
+   */
+  console.log(`  Registering ${siteUrl} and publishing the content schema…`)
+
+  const registered = await fetch(`${platform}/api/u90/register`, {
+    body: JSON.stringify({ siteUrl }),
+    headers: {
+      Authorization: `Bearer ${credentials.revalidateSecret}`,
+      'Content-Type': 'application/json',
+    },
+    method: 'POST',
+  }).catch(() => fail(`Could not reach ${platform} to register.`))
+
+  const result = await registered.json().catch(() => ({}))
+
+  if (!registered.ok) {
+    fail(
+      `${result.error ?? `Registration failed (HTTP ${registered.status}).`}\n\n` +
+        '  The credentials are saved, so once the site is reachable at that URL you can\n' +
+        `  finish with:  curl -X POST ${platform}/api/u90/register \\\n` +
+        '                  -H "Authorization: Bearer $REVALIDATE_SECRET" \\\n' +
+        `                  -H 'Content-Type: application/json' -d '{"siteUrl":"${siteUrl}"}'`,
+    )
+  }
+
+  console.log(`
+────────────────────────────────────────────────────────────────────────
+  ${credentials.tenantSlug} is connected.
+
+  ${result.blocks ?? 0} block(s) published. The client's dashboard now renders
+  from this repo's own schema — change a block here and it appears there on
+  the next deploy.
+
+  ${ENV_FILE} holds the credentials. Add the same three values to your
+  hosting environment; they are not printed here on purpose.
+────────────────────────────────────────────────────────────────────────
+`)
+}
+
+await run()