Files
orca/docs/site
Neil c097acc64e fix(editor): new files use the owning host's line ending; add End of Line setting (#43253)
* fix(editor): give new files the owning host's line ending, add End of Line setting

A file with no line breaks yet took the ending of the OS the window runs on,
so a Windows client wrote CRLF into files on WSL hosts and Linux SSH hosts.
Such models now adopt the ending of the host that owns the file (LF on Linux
and macOS, CRLF on native Windows), and Settings > General > Editor gains an
End of Line choice (Auto, LF, CRLF). Files with line breaks keep theirs.

Fixes #43216

* fix(editor): resolve paired-host files by endpoint and keep new-file EOL through undo

- Resolve a file's host from its endpoint-relative authority, so a file on a
  WSL host or paired server reads that host's OS instead of this client's.
- Only a WSL host's own files fall back to Linux; SSH targets behind it do not.
- Track whether a model was loaded with line breaks, and keep a new model on
  its chosen ending through undo, late host reports, and setting changes.
- A model without line breaks adopts the ending of external text written in.
- Read remote OS facts directly so the selector builds no translated strings.
- Docs describe Auto by where the workspace runs (Windows projects in WSL get LF).

* fix(editor): keep undo valid across late EOL conversion; respect text written while unmounted

- Convert typed lines with an undoable pushEOL step instead of a bare setEOL,
  whose stale offsets corrupted Undo. Only a new choice (late host report or
  setting change) converts multiline text, so Undo of the conversion sticks.
- Record outside text with line breaks on the model from the content-sync
  paths, so a remounted editor never converts text the user did not type.

* fix(editor): never convert a new file's line endings once its lines are saved

A clean buffer with line breaks matches the file on disk, so it is treated as
an existing file: changing End of Line later no longer converts it, marks it
dirty, and lets autosave rewrite it. Only typed, unsaved lines are converted.

* fix(editor): treat a new file as saved only when its bytes match disk

The dirty flag ignores Markdown trailing whitespace, so a clean flag did not
prove typed line breaks were saved. Compare the model text with the buffer's
last known disk signature instead. Also type the line-ending state by its
model shape for the anti-slop lint, localize the LF/CRLF labels, and note in
the docs that autosaved lines keep their ending if the host reports later.

* fix(editor): only set a new file's line ending while it has at most one line

Converting text that already has line breaks kept running into cases where
saved or in-flight lines were rewritten. The editor now sets the ending only
while the model has at most one line, at mount and whenever the choice
changes, and re-applies it when Undo returns to one line. Text with line
breaks is never converted. This removes the multi-line conversion, its undo
step, the per-model state and the disk-signature check.

* fix(editor): keep an existing file's line ending after it is emptied

A model that already had line breaks when the editor mounted, or got them
from a programmatic or outside write, is flagged as an existing file and
never has its ending set again, so emptying and retyping it keeps the file's
ending. Line breaks the user typed do not set the flag, so Undo back to one
line still restores the chosen ending. Scope the docs sentence on outside text.

* fix(editor): carry a buffer's line ending through model rekeys and renames

A replacement model was built from text and language alone, so an emptied
or one-line existing file lost its ending and existing-file status. The rekey
carry now copies both to the model it creates. A rename remounts the editor
under a new view id, so the rename records the old model and the remount
carries an unsaved draft the same way. Existing models at the destination are
never touched.

* fix(editor): hand a renamed buffer's line ending over as a snapshot

The rename handoff stored the old model's address, which model cleanup could
dispose before the renamed tab mounted, and records were never cleared. The
rename now snapshots { ending, existing-file } from the old model, only for a
tab with an unsaved draft, keyed by the new tab id. The tab-close cleanup
drops it, and the remount applies it only to the model it builds from the
draft. Same-view re-keys still carry from the live model.
2026-11-16 14:49:08 -08:00
..

@orca/docs

This package contains the product documentation and public media intended to ship alongside Orca's source code.

Open-source product documentation for Orca, served at /docs (same URL shape as https://orca.dev/docs).

This package is a self-contained Next.js app. It is intentionally not a root monorepo workspace member, so installing Electron app dependencies does not pull Next/fumadocs.

Local development

Use Node.js 24 and the pnpm version pinned in package.json. CI reads the Node.js version from this package's engines.node field.

cd docs/site
pnpm install
pnpm dev

Open http://localhost:3004/docs.

Linting

Run pnpm lint inside this directory. The isolated Oxlint configuration keeps the native equivalents of the previous Next.js, React, React hooks and accessibility checks at their existing severities, including alt text on Next.js Image components. Generated Next.js and MDX output is excluded. Oxlint also reports its default correctness warnings.

The migration does not provide equivalents for React's deprecated-API check, React Compiler configuration/gating diagnostics, or Next.js's relative location.assign advisory. JSX variable-use bookkeeping is handled by Oxlint's parser. Keep TypeScript and the production Next.js build in the validation workflow; this is not a claim of complete ESLint rule parity.

Production build

cd docs/site
pnpm install
pnpm build
pnpm start

pnpm start serves the production build on port 3004. Paths:

Path Purpose
/ Redirects to /docs
/docs Docs index
/docs/... Nested doc pages from content/docs
/docs/api/search Fumadocs search index
/docs/og/... Per-page Open Graph image route

Layout

  • content/docs/ — MDX pages + meta.json navigation
  • public/docs/ — docs-only media, logo, and favicon (GIFs, posters, screenshots)
  • src/app/docs/ — fumadocs routes, OG images
  • src/components/ — docs-scoped chrome (header/footer/search), not marketing site

Updating content

Treat the documentation tree as a deliberate publication boundary. Before importing source material, review the diff for internal references, credentials, third-party media rights, and feature/version claims, then copy only approved pages and assets. Keep the app shell and deployment configuration in this repository so a docs-only pull request can be reviewed and built independently.

Same-domain routing

The docs app is a separate Vercel project (the docs zone) and keeps the public /docs URL namespace. The marketing site remains the default zone for orca.dev; configure its Next/Vercel proxy with these beforeFiles rewrites, replacing DOCS_ORIGIN with the docs project's production URL:

return {
  beforeFiles: [
    {
      source: '/docs',
      destination: `${DOCS_ORIGIN}/docs`
    },
    {
      source: '/docs/:path*',
      destination: `${DOCS_ORIGIN}/docs/:path*`
    },
    {
      source: '/docs-static/:path*',
      destination: `${DOCS_ORIGIN}/docs-static/:path*`
    }
  ]
}

/docs-static is the docs zone's assetPrefix; it prevents _next asset collisions with the marketing zone. Keep the rewrites in the default zone and use ordinary <a> links when navigating between zones. Do not add basePath: '/docs' to this app: its route tree and Fumadocs baseUrl already include /docs, so doing so would publish /docs/docs/... URLs. If a future deployment needs basePath, first move the route tree to an unprefixed src/app/[[...slug]] shape and update every generated/link URL together.

Deploy (Vercel)

  1. Create a Vercel project with Root Directory unset (.). The workflow invokes Vercel from docs/site, so that directory is already the deployment root; setting it again would resolve docs/site/docs/site. Leave automatic Git deployments disabled so this workflow remains the only deployment path.
  2. Framework preset: Next.js. This package's engines.node selects Node.js 24 for Vercel builds and functions. vercel.json pins install (pnpm install --frozen-lockfile) and build (pnpm build) over the dashboard settings; this package has its own lockfile beside the root workspace.
  3. Set GitHub Actions secrets (required by the production deploy job):
    • VERCEL_TOKEN
    • VERCEL_ORG_ID
    • VERCEL_PROJECT_ID (docs project, not the marketing site)
  4. Protect the docs-production GitHub environment with required reviewers and custom deployment branch policies for main and v* tags. The release-cut dispatch runs from main; the direct published-release fallback runs from a stable tag, while the workflow still authorizes only exact stable tags.
  5. Prepare the three rewrites above in the orca.dev marketing project, but leave them disabled until the docs deployment is verified. A Vercel custom domain cannot delegate only /docs by itself; the default zone must proxy both page/API/media requests and /docs-static assets. Keep the marketing project's old docs routes available for rollback during the transition; putting the proxy rules in beforeFiles ensures they win once enabled.
  6. Deploy a stable desktop tag that contains docs/site, verify the docs origin, then enable the marketing rewrites. Tags cut before this package was added cannot bootstrap the docs project because production intentionally checks out the tag's exact commit. Remove the old marketing docs routes in a follow-up after the proxy is stable.

.github/workflows/docs.yml runs credential-free checks for every pull request. It intentionally does not deploy PR previews: a PR-controlled build must not receive Vercel credentials. A maintainer can add a separate trusted preview workflow later. Production deploys only from an authorized stable desktop release: an exact vX.Y.Z tag, a published non-prerelease release, and the github-actions[bot] release author. Manual dispatch must run from the default branch and name an existing release that meets the same checks. Mobile, prerelease, draft, and human-authored releases are skipped. Fork pull requests remain build-only because GitHub does not expose deployment secrets to fork jobs.

Versioning

versioning.config.ts keeps the current unversioned /docs URLs stable while reserving content/versions/<id> for future snapshots. Versioned routes are not live yet; when they are needed, add the corresponding loader/routes and a version entry. The release workflow can then deploy them without a trigger change.

Isolation from the desktop app

  • Own package.json + pnpm-lock.yaml under docs/site/
  • Not listed in the root pnpm-workspace.yaml; its own pnpm-workspace.yaml makes it a separate workspace root and holds its pnpm settings, which pnpm 12 ignores under --ignore-workspace
  • Engineering notes remain in repo-root docs/ — do not confuse with this package