@lincyaw/kernel 1.0.0-rc.15 → 1.0.0-rc.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lincyaw/kernel",
3
- "version": "1.0.0-rc.15",
3
+ "version": "1.0.0-rc.16",
4
4
  "description": "Presmium's shared kernel: the IR and plugin contracts, the service registry, anchors and checks",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -0,0 +1,148 @@
1
+ /**
2
+ * Pictures of a document as its presentation shows it, taken by the workspace service in a headless browser: the rest
3
+ * frame of each step, or a moment into a step's animation, with the boxes of the elements an agent asks about. Agents
4
+ * (over MCP) check animations and layout with it instead of scripting a browser.
5
+ */
6
+
7
+ /** At most this many pictures a request: each is one image in a tool result. */
8
+ export const CAPTURE_MAX_FRAMES = 12
9
+ /** At most this many boxes a picture reports for `measure`. */
10
+ export const CAPTURE_MAX_BOXES = 200
11
+
12
+ export interface SlideCaptureRequest {
13
+ /** The page (section) id, or its number from 1. */
14
+ section: string
15
+ /** The steps to show, from 0; every step of the page when omitted. */
16
+ steps?: number[]
17
+ /** Milliseconds into each step's animation; each step's rest frame (its final state) when omitted. */
18
+ at?: number[]
19
+ appearance?: 'light' | 'dark'
20
+ /** Device pixels per slide pixel. */
21
+ scale?: 1 | 2
22
+ /** A region of the slide, in slide pixels. */
23
+ clip?: { x: number, y: number, width: number, height: number }
24
+ /** A CSS selector: the boxes of the matching elements in the slide are reported, in slide pixels. */
25
+ measure?: string
26
+ /**
27
+ * How the presentation reaches each step: `direct` (default) draws it from its step and moment; `backward` shows the
28
+ * step after it first and goes back as a presenter does, with the page's own clock, to check that going back works.
29
+ */
30
+ arrive?: 'direct' | 'backward'
31
+ /** Draw the presentation's captions over the slide (default true); false shows the whole slide, the narration being in `narration`. */
32
+ captions?: boolean
33
+ }
34
+
35
+ export interface ReadingCaptureRequest {
36
+ /** The page (section) id, or its number from 1. */
37
+ section: string
38
+ /** The window's width in CSS pixels (default 1280; 390 for a phone). */
39
+ width?: number
40
+ appearance?: 'light' | 'dark'
41
+ /** Device pixels per CSS pixel. */
42
+ scale?: 1 | 2
43
+ /** A CSS selector: the boxes of the matching elements in the page's section are reported, in CSS pixels. */
44
+ measure?: string
45
+ }
46
+
47
+ export interface CapturedReading {
48
+ section: string
49
+ /** The PNG file of the picture, in the service's state directory. */
50
+ file: string
51
+ /** The section's size in CSS pixels; the picture is cut at `CAPTURE_MAX_HEIGHT`. */
52
+ width: number
53
+ height: number
54
+ cut: boolean
55
+ boxes?: CapturedBox[]
56
+ }
57
+
58
+ export interface ReadingCaptureResult {
59
+ document: string
60
+ width: number
61
+ frames: CapturedReading[]
62
+ problems: string[]
63
+ }
64
+
65
+ /** The tallest picture of a reading page's section, in CSS pixels. */
66
+ export const CAPTURE_MAX_HEIGHT = 8000
67
+
68
+ export interface CapturedBox {
69
+ x: number
70
+ y: number
71
+ width: number
72
+ height: number
73
+ visible: boolean
74
+ /** The start of the element's text. */
75
+ text: string
76
+ /** Its `id`, `class` and `data-*` attributes. */
77
+ attributes: Record<string, string>
78
+ }
79
+
80
+ export interface CapturedSlide {
81
+ section: string
82
+ slide: number
83
+ step: number
84
+ /** Milliseconds into the step, or null for its rest frame. */
85
+ at: number | null
86
+ /** The step's narration (its script), as text: what the captions show. */
87
+ narration: string
88
+ /** The PNG file of the picture, in the service's state directory. */
89
+ file: string
90
+ width: number
91
+ height: number
92
+ boxes?: CapturedBox[]
93
+ }
94
+
95
+ export interface SlideCaptureResult {
96
+ document: string
97
+ /** The slide's size in slide pixels. */
98
+ shape: { width: number, height: number }
99
+ frames: CapturedSlide[]
100
+ /** What failed in the page while it was drawn: component errors, page errors. */
101
+ problems: string[]
102
+ }
103
+
104
+ export interface OverviewCaptureRequest {
105
+ /** Each page's last step (default), or every step of every page. */
106
+ steps?: 'last' | 'all'
107
+ appearance?: 'light' | 'dark'
108
+ /** Thumbnails a row on a sheet (default 4). */
109
+ columns?: number
110
+ /** Draw the presentation's captions over the slides (default true). */
111
+ captions?: boolean
112
+ }
113
+
114
+ export interface OverviewCaptureResult {
115
+ document: string
116
+ /** The directory of the pictures, named so that they sort in reading order (`03-12-page.png`: page 3, step 12 from 0). */
117
+ dir: string
118
+ frames: { section: string, slide: number, step: number, file: string, narration: string }[]
119
+ /** `narration.md` beside the pictures: each picture's narration under its file name. */
120
+ narrationFile: string
121
+ /** Sheets of thumbnails, at most `CAPTURE_SHEET_SIZE` each, in order. */
122
+ sheets: string[]
123
+ problems: string[]
124
+ }
125
+
126
+ /** Thumbnails on one overview sheet; and the most pictures an overview takes. */
127
+ export const CAPTURE_SHEET_SIZE = 20
128
+ export const CAPTURE_MAX_OVERVIEW = 400
129
+
130
+ export interface DocumentCapture {
131
+ /** The pictures, with their PNG bytes in the order of `frames`. */
132
+ slides(document: string, request: SlideCaptureRequest, signal?: AbortSignal): Promise<SlideCaptureResult & { images: Uint8Array[] }>
133
+ /** A page of the reading version (the web page), with its PNG bytes. */
134
+ reading(document: string, request: ReadingCaptureRequest, signal?: AbortSignal): Promise<ReadingCaptureResult & { images: Uint8Array[] }>
135
+ /** Every page's rest frames as the presentation shows them, as files and as sheets of thumbnails (the images). */
136
+ overview(document: string, request: OverviewCaptureRequest, signal?: AbortSignal): Promise<OverviewCaptureResult & { images: Uint8Array[] }>
137
+ }
138
+
139
+ /** The hook a viewer page opened with `?capture` installs, which the capturing browser drives. */
140
+ export interface CaptureHook {
141
+ /** A slide at a step: drawn at the moment `at` (its rest frame when omitted), or reached going back from the step after. */
142
+ show(position: { section: string, step: number, at?: number, arrive?: 'direct' | 'backward' }): Promise<{ problems: string[] }>
143
+ /** A section of the reading page, scrolled through so that its components load, at rest. */
144
+ read(section: string): Promise<{ problems: string[] }>
145
+ }
146
+
147
+ export const CAPTURE_HOOK = 'presmiumCapture'
148
+ export const CAPTURE_PARAM = 'capture'
@@ -10,6 +10,9 @@ export const PREVIEW_PARAM = 'presmium-preview'
10
10
  /** The workbench's appearance when it loads a preview (`dark` or `light`), so that the page's first paint matches it. */
11
11
  export const PREVIEW_APPEARANCE_PARAM = 'presmium-appearance'
12
12
 
13
+ /** `?captions=off` starts a presentation with its captions off (a reader turns them on again with the captions button). */
14
+ export const CAPTIONS_PARAM = 'captions'
15
+
13
16
  export const PREVIEW_REVISION = 'presmiumRevision'
14
17
 
15
18
  export const AUTHOR_MARKS_CLASS = 'pm-author-marks'
package/src/contracts.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  export * from './contracts/agent.ts'
2
2
  export * from './contracts/authoring.ts'
3
+ export * from './contracts/capture.ts'
3
4
  export * from './contracts/document-reads.ts'
4
5
  export * from './contracts/anchors.ts'
5
6
  export * from './contracts/checks.ts'
package/src/ir.ts CHANGED
@@ -318,6 +318,11 @@ export interface Renderer {
318
318
  dev?(doc: IRDocument, ctx: RenderContext): Promise<RenderDevServer>
319
319
  buildSite?(site: SiteSpec, ctx: RenderContext): Promise<RenderOutput>
320
320
  devSite?(site: SiteSpec, ctx: RenderContext, compile: (dir: string) => Promise<IRDocument>): Promise<SiteDevServer>
321
+ /**
322
+ * What would fail in its output of the whole document (every form's blocks), found ahead of a build: run with the
323
+ * document's checks (`presmium check`). The web renderer's: the document's own code that does not bundle.
324
+ */
325
+ check?(doc: IRDocument, ctx: RenderContext): Promise<Finding[]>
321
326
  }
322
327
 
323
328
  export interface SiteDocument {
@@ -364,6 +369,11 @@ export interface SiteDevServer {
364
369
  * With `wait`, a build still running after the wait rejects with `PreviewPreparing`; a failed build with its reason.
365
370
  */
366
371
  app?(dir: string, wait?: boolean): Promise<string | undefined>
372
+ /**
373
+ * The files of document `dir`'s own code that the bundle its pages load now leaves out, since they do not bundle:
374
+ * each module that imports one fails alone when the document shows it (`app` rejects when the whole does not bundle).
375
+ */
376
+ codeFindings?(dir: string): Finding[]
367
377
  close(): Promise<void>
368
378
  }
369
379
 
package/src/node/index.ts CHANGED
@@ -27,3 +27,5 @@ export { validateProjectPlan, validateProjectApply } from './projects.ts'
27
27
  export { validateDocumentWorkspaceImageInspect, validateDocumentWorkspaceImageImport } from './document-image.ts'
28
28
  export { systemLocale } from './locale.ts'
29
29
  export { OperatorSpeechSettings, operatorSpeechSecrets, SpeechSettingsError } from './operator-speech.ts'
30
+ export { devStateFile, readServiceState, removeServiceState, serveStateDir } from './service-state.ts'
31
+ export type { ServiceState } from './service-state.ts'
@@ -0,0 +1,52 @@
1
+ import { createHash } from 'node:crypto'
2
+ import { readFileSync, rmSync } from 'node:fs'
3
+ import { homedir } from 'node:os'
4
+ import { join } from 'node:path'
5
+ import { isRecord } from '../errors.ts'
6
+
7
+ /** What a running Presmium server records for local clients: its address, its MCP endpoint and token, its process. */
8
+ export interface ServiceState {
9
+ url: string
10
+ mcp: string
11
+ token: string
12
+ pid: number
13
+ }
14
+
15
+ /** The state directory of the workspace service (`presmium serve`, and the one `presmium studio` starts) of `root`. */
16
+ export function serveStateDir(root: string, env: NodeJS.ProcessEnv = process.env): string {
17
+ const base = env.XDG_CACHE_HOME || join(homedir(), '.cache')
18
+ return join(base, 'presmium', 'serve', createHash('sha256').update(root).digest('hex').slice(0, 16))
19
+ }
20
+
21
+ /** The state file `presmium dev` writes beside the document it previews. */
22
+ export function devStateFile(deckDir: string): string {
23
+ return join(deckDir, '.presmium', 'server.json')
24
+ }
25
+
26
+ const alive = (pid: number): boolean => {
27
+ try {
28
+ process.kill(pid, 0)
29
+ return true
30
+ } catch (error) {
31
+ return (error as NodeJS.ErrnoException).code === 'EPERM'
32
+ }
33
+ }
34
+
35
+ /** The state of the server that wrote `file`, while that process runs. */
36
+ export function readServiceState(file: string): ServiceState | undefined {
37
+ try {
38
+ const state: unknown = JSON.parse(readFileSync(file, 'utf8'))
39
+ if (!isRecord(state) || typeof state.url !== 'string' || typeof state.mcp !== 'string' || typeof state.token !== 'string' || typeof state.pid !== 'number') return undefined
40
+ return alive(state.pid) ? { url: state.url, mcp: state.mcp, token: state.token, pid: state.pid } : undefined
41
+ } catch {
42
+ return undefined
43
+ }
44
+ }
45
+
46
+ /** Removes `file` when it is still this process's: a server that stopped leaves no address behind. */
47
+ export function removeServiceState(file: string, pid = process.pid): void {
48
+ try {
49
+ const state: unknown = JSON.parse(readFileSync(file, 'utf8'))
50
+ if (isRecord(state) && state.pid === pid) rmSync(file, { force: true })
51
+ } catch {}
52
+ }
@@ -1,6 +1,6 @@
1
1
  import { PREVIEW_EVENTS_PARAM, previewEnvelope } from './contracts/preview.ts'
2
2
  import type { PreviewCommand, PreviewEventSubscription, PreviewEventTarget, PreviewEventMessage } from './contracts/preview.ts'
3
- import { previewNonce } from './preview-frame.ts'
3
+ import { parentOrigins, previewNonce } from './preview-frame.ts'
4
4
 
5
5
  /** Uses the existing preview-ready handshake, origin fence and nonce; never opens a network connection. */
6
6
  export interface PreviewEvents {
@@ -17,8 +17,9 @@ export function createPreviewEvents(origins: readonly string[], document: string
17
17
  const connection = crypto.randomUUID()
18
18
  const readers = new Map<string, { target: PreviewEventTarget, received(message: PreviewEventMessage): void }>()
19
19
  let ready = false, stopped = false, parked = false
20
+ const targets = parentOrigins(origins)
20
21
  const post = (message: Parameters<typeof previewEnvelope>[1]) => {
21
- if (!stopped) for (const origin of origins) window.parent.postMessage(previewEnvelope(nonce, message), origin)
22
+ if (!stopped) for (const origin of targets) window.parent.postMessage(previewEnvelope(nonce, message), origin)
22
23
  }
23
24
  const subscribe = (id: string, target: PreviewEventTarget) => post({ type: 'events-subscribe', connection, id, target })
24
25
  const park = () => {
@@ -4,7 +4,7 @@ import { keyBelongsToTarget, watchFocusSource } from './keyboard.ts'
4
4
  import { errorMessage } from './errors.ts'
5
5
  import { sameProductionBinding } from './contracts/production.ts'
6
6
  import type { ProductionBinding, ProductionPlaybackState } from './contracts/production.ts'
7
- import { isPreviewActive, previewNonce, previewWindowName, routePreviewReports } from './preview-frame.ts'
7
+ import { isPreviewActive, parentOrigins, previewNonce, previewWindowName, routePreviewReports } from './preview-frame.ts'
8
8
  import type { PreviewFrame, PreviewPage, PreviewProblem, PreviewTextHandle } from './preview-frame.ts'
9
9
 
10
10
  // The page's side of the preview protocol, apart from `preview-frame.ts` so that only a page the workbench embeds loads
@@ -819,9 +819,10 @@ export function connectPreviewFrame(page: PreviewPage): PreviewFrame | undefined
819
819
  root.dataset.presmiumPreview = 'on'
820
820
  installStyle()
821
821
 
822
+ const targets = parentOrigins(page.origins)
822
823
  const post = (message: PreviewReport) => {
823
824
  if (state.stopped || (!state.active && message.type !== 'ready' && message.type !== 'activity' && message.type !== 'playback-paused' && message.type !== 'production-playback-result')) return
824
- for (const origin of page.origins) window.parent.postMessage(previewEnvelope(nonce, message), origin)
825
+ for (const origin of targets) window.parent.postMessage(previewEnvelope(nonce, message), origin)
825
826
  }
826
827
  const releaseReports = routePreviewReports(post)
827
828
  // Stored drafts must wait until the parent's first ready handshake, and an
@@ -100,6 +100,19 @@ export function previewAppearance(): 'dark' | 'light' | undefined {
100
100
  return given === 'dark' || given === 'light' ? given : undefined
101
101
  }
102
102
 
103
+ /**
104
+ * The allowed origins the page's parent can have: its own when the page can tell (`location.ancestorOrigins`, else the
105
+ * referrer) and it is allowed, else all of them. Posting only to the parent's own origin spares the browser a warning for
106
+ * each origin the parent does not have.
107
+ */
108
+ export function parentOrigins(origins: readonly string[]): readonly string[] {
109
+ let known: string | undefined
110
+ try {
111
+ known = location.ancestorOrigins?.[0] ?? (document.referrer ? new URL(document.referrer).origin : undefined)
112
+ } catch {}
113
+ return known && origins.includes(known) ? [known] : origins
114
+ }
115
+
103
116
  /**
104
117
  * The Content-Security-Policy of a served page: the site itself may embed it (a home page that plays a document's
105
118
  * presentation in a frame works in `presmium serve` as in the built site), and so may the workbench's origins.