@kernhq/module-quire 0.11.0 → 0.12.0

package/src/client/pages/PageView.svelte

@@ -14,20 +14,24 @@ import {
   relativeTime,
   Skeleton,
   session,
+  Tooltip,
   toast,
 } from '@kernhq/ui'
 import { createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { untrack } from 'svelte'
 import { getQuireApi } from '../api-instance.js'
 import CommentsPanel from '../components/CommentsPanel.svelte'
 import ConfirmDialog from '../components/ConfirmDialog.svelte'
 import FavoriteStar from '../components/FavoriteStar.svelte'
 import PageEditor from '../components/PageEditor.svelte'
 import PageLabels from '../components/PageLabels.svelte'
+import PublishDialog from '../components/PublishDialog.svelte'
 import VersionHistory from '../components/VersionHistory.svelte'
 import { type CoreApi, toPerson } from '../core-api.js'
 import DatabaseView from '../database/DatabaseView.svelte'
 import { t } from '../i18n.js'
 import { canQuire } from '../permissions.js'
+import { publicSiteUrl } from '../public-url.js'
 import { quireKeys } from '../query.js'
 
 /**
@@ -148,19 +152,69 @@ $effect(() => {
   dirty = false
 })
 
+/**
+ * The title saves as you type, not only when you leave the field.
+ *
+ * It used to save on `blur` alone, and nothing else — so typing a name and then going somewhere
+ * without blurring first (a keyboard shortcut, ⌘K, closing the tab, any programmatic navigation)
+ * threw the name away and left the page called "Untitled" for ever. Measured against the live
+ * stack: fifteen seconds after typing, `mod_quire.pages.title` was still `''`; it only ever became
+ * the typed value on blur.
+ *
+ * A page's *body* has never had this problem, because it is a Y.Doc the collab service persists on
+ * its own schedule. The title is not — it is a plain column behind `pages.update` — so the schedule
+ * has to be written here. `docs/adr/0006` says the title should live in the Y.Doc beside the body
+ * for exactly this reason, and because two people renaming at once currently clobber each other;
+ * that is a larger change and this is not a substitute for it.
+ */
+const TITLE_SAVE_AFTER_MS = 700
+let titleTimer: ReturnType<typeof setTimeout> | null = null
+/* Set in the same tick as the call, because `isPending` arrives a render late and two saves would
+   race to write the same column in an order neither of them chose. */
+let savingTitle = false
+
+function queueTitleSave() {
+  if (titleTimer) clearTimeout(titleTimer)
+  titleTimer = setTimeout(() => {
+    titleTimer = null
+    void saveTitle()
+  }, TITLE_SAVE_AFTER_MS)
+}
+
 async function saveTitle() {
-  if (!doc || !dirty) return
+  if (titleTimer) {
+    clearTimeout(titleTimer)
+    titleTimer = null
+  }
+  if (!doc || !dirty || savingTitle) return
   const next = title.trim()
   if (next === doc.title) {
     dirty = false
     return
   }
-  await api.pages.update({ workspaceId, pageId, title: next })
-  dirty = false
-  await client.invalidateQueries({ queryKey: quireKeys.page(workspaceId, pageId) })
-  await client.invalidateQueries({ queryKey: quireKeys.tree(workspaceId, doc.spaceId) })
+  savingTitle = true
+  try {
+    await api.pages.update({ workspaceId, pageId, title: next })
+    dirty = false
+    await client.invalidateQueries({ queryKey: quireKeys.page(workspaceId, pageId) })
+    await client.invalidateQueries({ queryKey: quireKeys.tree(workspaceId, doc.spaceId) })
+  } finally {
+    savingTitle = false
+  }
 }
 
+/* Leaving the page mid-word must not lose the word. */
+$effect(() => {
+  void pageId
+  return () => {
+    if (titleTimer) {
+      clearTimeout(titleTimer)
+      titleTimer = null
+    }
+    if (untrack(() => dirty)) void saveTitle()
+  }
+})
+
 async function archive(archived: boolean) {
   if (!doc) return
   await api.pages.archive({ workspaceId, pageId, archived })
@@ -195,6 +249,73 @@ async function revert() {
   }
 }
 
+// -----------------------------------------------------------------------------------------------
+// Whether this page is on the internet
+// -----------------------------------------------------------------------------------------------
+
+/**
+ * The share dialog owns publishing; this owns the one thing the *page* has to say about it.
+ *
+ * Both queries are gated on `quire.page.publish` because `publications.list` asks for it, and a
+ * query that is certain to be refused is a 403 in everybody else's network tab and an indicator
+ * that never appears either way. The consequence is worth stating plainly: **somebody who cannot
+ * publish does not see the "Public" chip.** That is the wrong way round for a reader who would
+ * like to know, and it is the only shape available until there is a procedure that answers "is this
+ * page public" without asking to publish it — a chip is not worth a new public surface.
+ */
+let shareOpen = $state(false)
+const canPublish = $derived(canQuire('pagePublish'))
+
+const publicationsQuery = createQuery(() => ({
+  queryKey: quireKeys.publications(workspaceId, doc?.spaceId ?? ''),
+  enabled: canPublish && Boolean(workspaceId && doc?.spaceId),
+  queryFn: () => api.publications.list({ workspaceId, spaceId: doc?.spaceId ?? '' }),
+}))
+
+/**
+ * The space's tree, only once something in it has been published.
+ *
+ * Same key as the sidebar's, so on a page reached through the sidebar this costs nothing at all;
+ * and a space with no published site never asks for it.
+ */
+const spaceTreeQuery = createQuery(() => ({
+  queryKey: quireKeys.tree(workspaceId, doc?.spaceId ?? ''),
+  enabled: canPublish && (publicationsQuery.data?.length ?? 0) > 0 && Boolean(workspaceId && doc?.spaceId),
+  queryFn: () => api.pages.tree({ workspaceId, spaceId: doc?.spaceId ?? '', includeArchived: false }),
+}))
+
+/**
+ * The publication a signed-out stranger could read *this* page through, or null.
+ *
+ * It reproduces the server's prune rather than asking whether the page is somewhere under a root:
+ * every page on the way up — this one, each ancestor, and the root itself — has to be a `page`,
+ * unarchived, not opted out and actually published, because that is exactly what the recursive walk
+ * behind `public.site` descends through. Getting this looser would put a "Public" chip on a page
+ * strangers cannot open, which is the mistake that teaches somebody the chip means nothing.
+ */
+const publicVia = $derived.by((): { slug: string; root: boolean } | null => {
+  const rows = publicationsQuery.data ?? []
+  const here = doc
+  if (!here || rows.length === 0) return null
+  if (here.kind !== 'page' || here.archivedAt || here.deletedAt || !here.publishedVersionId) return null
+  const nodes = spaceTreeQuery.data
+  const byId = new Map((nodes ?? []).map((node) => [node.id, node]))
+  for (const row of rows) {
+    if (row.rootPageId === here.id) return { slug: row.slug, root: true }
+    if (!row.includeDescendants || !nodes) continue
+    let at = byId.get(here.id)
+    let guard = 0
+    while (at && guard++ < 1000) {
+      if (at.kind !== 'page' || at.archivedAt || at.excludedFromPublic || !at.hasPublishedVersion) break
+      if (at.id === row.rootPageId) return { slug: row.slug, root: false }
+      at = at.parentId ? byId.get(at.parentId) : undefined
+    }
+  }
+  return null
+})
+
+const publicUrl = $derived(publicVia ? publicSiteUrl({ workspaceSlug, slug: publicVia.slug }) : '')
+
 // -----------------------------------------------------------------------------------------------
 // Watching, recording, and the way this page is deleted
 // -----------------------------------------------------------------------------------------------
@@ -402,6 +523,7 @@ async function undoTrash(workspace: string, id: string, spaceId: string, title:
             oninput={(e) => {
               title = (e.currentTarget as HTMLInputElement).value
               dirty = true
+              queueTitleSave()
             }}
             onblur={saveTitle}
             onkeydown={(e) => {
@@ -451,6 +573,25 @@ async function undoTrash(workspace: string, id: string, spaceId: string, title:
                 },
               ]
             : []),
+          /*
+           * Only a `page`, and only for somebody who may publish.
+           *
+           * A live doc and a database have no published version — `publishing.publish` refuses
+           * them — so a site rooted at one would serve nothing, and an entry that opens a dialog
+           * whose only outcome is an empty site is worse than an absent one. `page.publish` rather
+           * than `page.edit`, matching every procedure the dialog calls: in a space where writing
+           * is open and publishing is not, those are different people.
+           */
+          ...(doc.kind === 'page' && canPublish
+            ? [
+                {
+                  id: 'share-web',
+                  label: t('share_web'),
+                  icon: 'globe',
+                  onSelect: () => (shareOpen = true),
+                },
+              ]
+            : []),
           {
             id: 'watch',
             label: watching ? t('watch_stop') : t('watch'),
@@ -511,6 +652,30 @@ async function undoTrash(workspace: string, id: string, spaceId: string, title:
           ? t('edited_ago_by', { when: relativeTime(doc.updatedAt), who: editor.name })
           : t('edited_ago', { when: relativeTime(doc.updatedAt) })}
       </span>
+      <!--
+        Quiet, and a link.
+
+        "This page is on the internet" is a fact about the page, so it sits with the other facts
+        under the title rather than as a banner — but it is the only one of them worth clicking,
+        because the useful thing to do with it is to go and look at what strangers actually see.
+        The sentence explaining it is a tooltip rather than the label: the label has to survive
+        being one chip in a row of them, and the explanation is a whole sentence.
+      -->
+      {#if publicVia}
+        <Tooltip text={publicVia.root ? t('public_chip_root') : t('public_chip_child')}>
+          {#snippet children(props: Record<string, unknown>)}
+            <a
+              class="chip public"
+              href={publicUrl}
+              target="_blank"
+              rel="noreferrer noopener"
+              {...props}
+            >
+              <Icon name="globe" size={12} /> {t('public_chip')}
+            </a>
+          {/snippet}
+        </Tooltip>
+      {/if}
       {#if doc.kind === 'live'}
         <span class="chip"><Icon name="square-pen" size={12} /> {t('kind_live')}</span>
       {/if}
@@ -590,6 +755,14 @@ async function undoTrash(workspace: string, id: string, spaceId: string, title:
     publishedVersionId={doc.publishedVersionId}
   />
 
+  <PublishDialog
+    bind:open={shareOpen}
+    {workspaceId}
+    {workspaceSlug}
+    spaceId={doc.spaceId}
+    page={doc}
+  />
+
   <!--
     The body says nothing about numbers until it knows them. Naming a count before the tree has
     loaded would be the same silent lie in a smaller size — "it goes to the trash" for a page that
@@ -660,6 +833,24 @@ async function undoTrash(workspace: string, id: string, spaceId: string, title:
   align-items: center;
   gap: 4px;
 }
+/*
+ * The one chip that is a control, so it is the one that reads as one — a tinted pill with a hit
+ * area a finger can find. `--kern-accent-text` rather than `--kern-accent`: the flat accent is a
+ * fill colour and does not clear 4.5:1 as text on its own tint in either theme.
+ */
+.chip.public {
+  gap: 5px;
+  min-height: 22px;
+  padding-inline: 8px;
+  border-radius: var(--kern-r-full);
+  background: var(--kern-accent-tint);
+  color: var(--kern-accent-text);
+  font-weight: 500;
+  text-decoration: none;
+}
+.chip.public:hover {
+  background: var(--kern-accent-tint-2);
+}
 .body {
   margin-block-start: 22px;
 }

package/src/client/public-url.ts

@@ -0,0 +1,64 @@
+/**
+ * Where a published site lives, decided in exactly one place.
+ *
+ * The module's `public.*` procedures deliberately know nothing about this. They answer `path`
+ * relative to a publication — `''` for the front page, `guide/install` for a nested one — and take
+ * `basePath` as an argument, because one instance may serve a site under this prefix and another
+ * under a domain of its own. That is the right call on the server and it leaves somebody having to
+ * decide the address, so this file is that somebody: the share dialog shows what it returns, the
+ * header link opens it, and whatever route eventually renders a published page has to match it.
+ *
+ * **`/p/` is a literal segment before the workspace, not after it.** Every other Kern URL starts
+ * with the workspace — `/{workspace}/quire/{space}/{page}` — and a published site cannot, because
+ * the shell's top-level route is `[ws]`: `/{workspace}/p/…` would be inside the signed-in app,
+ * behind its guard, which is the one thing a public URL must not be. A static first segment sorts
+ * ahead of a dynamic one in SvelteKit, so `/p/…` is reachable signed out and cannot be shadowed by
+ * a workspace. The cost is that a workspace whose slug is exactly `p` would collide, which is why
+ * the segment is here as a constant rather than typed out at three call sites.
+ *
+ * The workspace is named by **slug, not id**. Both are equally public — the id is already in the
+ * API path this resolves to — but one of them is a uuid, and a customer publishing a handbook is
+ * publishing a URL they will print. Resolving the slug is one lookup the route layer already does
+ * for every other page in the product.
+ */
+export const PUBLIC_SITE_PREFIX = 'p'
+
+export interface PublicSiteAddress {
+  /** the workspace's slug, as it appears in every other Kern URL */
+  workspaceSlug: string
+  /** the publication's slug */
+  slug: string
+  /**
+   * A page's path *inside* the publication, as `public.site` and `public.page` report it. `''` is
+   * the front page, which is the whole of what the share dialog ever shows.
+   */
+  path?: string
+}
+
+/**
+ * The `basePath` argument `public.page` validates and builds its inter-page links from.
+ *
+ * Starts and ends with `/`, unreserved segments only — the contract refuses anything else, and the
+ * refusal is the point: `//evil.example/` is a protocol-relative URL wearing the costume of a local
+ * path, and a caller who could set it would repoint every link on somebody's published site.
+ */
+export function publicSiteBasePath({ workspaceSlug, slug }: PublicSiteAddress): string {
+  return `/${PUBLIC_SITE_PREFIX}/${encodeURIComponent(workspaceSlug)}/${encodeURIComponent(slug)}/`
+}
+
+/**
+ * The address to show somebody, absolute when there is an origin to be absolute against.
+ *
+ * `location` is read defensively rather than assumed: this module's client is source, built by the
+ * consumer, and a consumer that renders a screen on the server has no `location` at all. A relative
+ * address is still correct there — it is only the *copyable* one that has to be absolute.
+ */
+export function publicSiteUrl(address: PublicSiteAddress, origin?: string): string {
+  const root = origin ?? (typeof location === 'undefined' ? '' : location.origin.replace(/\/+$/, ''))
+  const trail = (address.path ?? '')
+    .split('/')
+    .filter((segment) => segment.length > 0)
+    .map(encodeURIComponent)
+    .join('/')
+  return `${root}${publicSiteBasePath(address)}${trail}`
+}

package/src/client/query.ts

@@ -38,6 +38,22 @@ export const quireKeys = {
   recents: (workspaceId: string) => ['quire', 'recent', workspaceId] as const,
   watchers: (workspaceId: string, pageId: string) => ['quire', 'watcher', workspaceId, pageId] as const,
 
+  /**
+   * Who has published what.
+   *
+   * `publication` is the entity `publications.create|update|remove` announce, so every screen
+   * holding one of these keys redraws when somebody else publishes or takes a site down — which
+   * matters more here than anywhere else in the module, because the thing that changed is whether
+   * strangers can read a page.
+   *
+   * `site` is under the same entity on purpose. It is the *anonymous* read of a published site —
+   * what the share dialog checks the URL against — and it is stale the instant the publication
+   * changes, so it must be invalidated by the same announcement rather than by remembering to.
+   */
+  publications: (workspaceId: string, spaceId: string) =>
+    ['quire', 'publication', workspaceId, spaceId] as const,
+  site: (workspaceId: string, slug: string) => ['quire', 'publication', workspaceId, 'site', slug] as const,
+
   /** the schema — properties and views — which every open tab of a database is drawing */
   database: (workspaceId: string, databaseId: string) =>
     ['quire', 'database', workspaceId, databaseId] as const,

package/src/contract/models.ts

@@ -87,6 +87,30 @@ export const PageNode = z.object({
   icon: z.string().nullable(),
   hasChildren: z.boolean(),
   archivedAt: Timestamp.nullable(),
+  /**
+   * Kept out of every publication, present and future — `publications.optOut` sets it.
+   *
+   * On the node rather than on `Page` because the only screen that reads it is a *list*: the share
+   * dialog draws one row per descendant with a switch on it, and a switch whose state has to be
+   * fetched page by page is a screen that opens with everything wrong and corrects itself. Two more
+   * booleans on a row the sidebar already loads for the whole space is the cheap end of that trade.
+   *
+   * `.default(false)` so a tree drawn by a client newer than its server still parses; the inferred
+   * output type is required either way, which is what makes both constructors supply it.
+   */
+  excludedFromPublic: z.boolean().default(false),
+  /**
+   * Whether a reader without edit rights has anything to be served — `publishedVersionId != null`,
+   * as a boolean, because the id itself addresses `versions.get` and a tree row has no business
+   * carrying it.
+   *
+   * Here for the same list as the flag above, and it is the half that stops that list lying. An
+   * opt-out switch on its own says "this page is public" about a page nobody has ever published,
+   * which is the wrong answer in the safe direction — and a screen that is wrong in the safe
+   * direction today is one nobody checks tomorrow. Always false for a `live` doc and a `database`:
+   * neither has a published version, because `publishing.publish` refuses anything but a `page`.
+   */
+  hasPublishedVersion: z.boolean().default(false),
 })
 export type PageNode = z.infer<typeof PageNode>
 
@@ -244,4 +268,57 @@ export const Watcher = z.object({
 })
 export type Watcher = z.infer<typeof Watcher>
 
+/**
+ * How a published site is coloured. `auto` follows the reader's own setting rather than the
+ * author's, which is the only one of the three that is a preference and not an instruction.
+ */
+export const PublicationTheme = z.enum(['auto', 'light', 'dark'])
+export type PublicationTheme = z.infer<typeof PublicationTheme>
+
+/**
+ * A page, and everything under it, at a URL a signed-out stranger can open.
+ *
+ * The row *is* the grant: no publication, no public page, and deleting it takes the site down. What
+ * a reader is served is the **pinned published version** of each page — `Page.publishedVersionId`
+ * and the HTML rendered onto it — never the live document and never the draft. A page with no
+ * published version is not public, whatever the tree says.
+ *
+ * There is no `passwordHash` here and there never should be. `hasPassword` is the whole of what a
+ * client needs: whether to ask. A hash is a hash, a salt and a cost, and shipping it to a browser
+ * turns an online guess into an offline one.
+ */
+export const Publication = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  /** the page the site is rooted at; its own published version is the front page */
+  rootPageId: Id,
+  /** false publishes exactly one page, which is what a single shared document wants */
+  includeDescendants: z.boolean(),
+  /**
+   * The URL segment. Unique per workspace and not beyond it — the public URL carries the workspace,
+   * so two customers both wanting `handbook` is not a collision. Lowercase by the same rule as
+   * `Space.key`: a URL that differs only in case is one URL to a person and two rows to Postgres.
+   */
+  slug: z
+    .string()
+    .min(2)
+    .max(64)
+    .regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/, 'lowercase letters, digits and dashes'),
+  /** whether a password is set — never the hash, and never the password */
+  hasPassword: z.boolean(),
+  /** null never expires; past means the URL is gone */
+  expiresAt: Timestamp.nullable(),
+  /** what a search result and a link preview say; empty falls back to the root page's own title */
+  seoTitle: z.string().max(200),
+  seoDescription: z.string().max(500),
+  ogImageUrl: z.string().max(2048).nullable(),
+  /** false sends `noindex`. Public and findable are different requests, and people mean both. */
+  indexable: z.boolean(),
+  theme: PublicationTheme,
+  createdBy: UserId.nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+})
+export type Publication = z.infer<typeof Publication>
+
 export const Ok = z.object({ ok: z.literal(true) })

package/src/contract/permissions.ts

@@ -101,9 +101,25 @@ export const quirePermissions = definePermissions([
  *     scope yet: `spaces.create` has no space to be scoped to.
  *   - `filter` — a list that omits what you may not see rather than refusing. "You may not open it"
  *     is a worse answer than not showing it, and `spaces.list` is deliberately the second.
+ *   - `public` — there is no principal to ask about. See below.
+ *
+ * **`public` is the one that needs saying out loud.** Every other value here answers "which scope is
+ * this permission resolved at"; `public` answers "this procedure asks nobody anything", which is a
+ * different kind of statement and the only one in this module that can leak a customer's private
+ * pages to the internet. It is spelled as a value rather than an omission so that adding one is a
+ * line in a review instead of a missing entry nobody sees, and `authz.int.test.ts` treats it as its
+ * own case: it calls the procedure once as a principal denied everything and once as a genuine
+ * anonymous stranger, and fails unless the two answers are byte-for-byte identical. That is the
+ * property that matters — a public surface that quietly shows an author more than it shows a
+ * stranger is one whose author tests it and never sees what the world sees.
+ *
+ * `permission` is still required for a `public` entry, and it names the permission that had to be
+ * held to *create the grant* — `quire.page.publish`, the one somebody used to make the publication.
+ * It is not a check this procedure performs. `module.test.ts` holds every entry to a permission the
+ * module declares, and there is no honest way to write "none" that keeps the rest of that check.
  */
 export interface ProcedureAuthz {
-  check: 'page' | 'space' | 'workspace' | 'filter'
+  check: 'page' | 'space' | 'workspace' | 'filter' | 'public'
   permission: string
 }
 
@@ -191,4 +207,40 @@ export const quireProcedureAuthz: Record<string, ProcedureAuthz> = {
 
   'publishing.publish': { check: 'page', permission: 'quire.page.publish' },
   'publishing.revert': { check: 'page', permission: 'quire.page.edit' },
+
+  /*
+   * A publication hands a page's whole subtree to the internet, so the question every one of these
+   * asks is about the **root page** — not the space, and not the workspace. `quire.page.publish` is
+   * already the permission that decides which version readers are served; deciding that the readers
+   * include everybody is the same decision one step further.
+   *
+   * `list` is the exception and is space-scoped, because "what has this space published" has no one
+   * page to resolve against. It filters as well: a publication whose root page the caller may not
+   * read is not named in the answer, for the same reason `pages.trash` does not name a title.
+   *
+   * `optOut` is `quire.page.publish` rather than `quire.page.edit` on purpose. Marking a page
+   * "never public" is a publishing decision about who may read it, not a change to what it says —
+   * and the two permissions are held by different people in a space where writing is open and
+   * publishing is not.
+   */
+  'publications.list': { check: 'space', permission: 'quire.page.publish' },
+  'publications.get': { check: 'page', permission: 'quire.page.publish' },
+  'publications.create': { check: 'page', permission: 'quire.page.publish' },
+  'publications.update': { check: 'page', permission: 'quire.page.publish' },
+  'publications.remove': { check: 'page', permission: 'quire.page.publish' },
+  'publications.optOut': { check: 'page', permission: 'quire.page.publish' },
+
+  /*
+   * The signed-out surface. Nothing here asks a permission, because there is nobody to ask about —
+   * see the note on `check: 'public'` above. What stands in for the permission check is that every
+   * query is scoped by the **publication**: its root page, the descendants that survive the prune,
+   * `excluded_from_public` false and a rendered published version. Workspace scope is what
+   * row-level security gives, and workspace scope is not publication scope.
+   */
+  'public.site': { check: 'public', permission: 'quire.page.publish' },
+  'public.page': { check: 'public', permission: 'quire.page.publish' },
+  'public.search': { check: 'public', permission: 'quire.page.publish' },
+  'public.sitemap': { check: 'public', permission: 'quire.page.publish' },
+  'public.robots': { check: 'public', permission: 'quire.page.publish' },
+  'public.unlock': { check: 'public', permission: 'quire.page.publish' },
 }